[Python-checkins] bpo-26978: Implement pathlib.Path.link_to (Using os.link) (GH-12990)

[Antoine Pitrou]

https://github.com/python/cpython/commit/6b5b013bcc22a27d6231c2796882e44ddb42be67
commit: 6b5b013bcc22a27d6231c2796882e44ddb42be67
branch: master
author: Joannah Nanjekye <33177550+nanjekyejoannah at users.noreply.github.com>
committer: Antoine Pitrou <antoine at python.org>
date: 2019-05-04T17:27:10+02:00
summary:

bpo-26978: Implement pathlib.Path.link_to (Using os.link) (GH-12990)

files:
A Misc/NEWS.d/next/Library/2019-04-28-01-52-39.bpo-26978.Lpm-SI.rst
M Doc/library/pathlib.rst
M Doc/whatsnew/3.8.rst
M Lib/pathlib.py
M Lib/test/test_pathlib.py

diff --git a/Doc/library/pathlib.rst b/Doc/library/pathlib.rst
index 450e8ff378a3..7a4a20dc6118 100644
--- a/Doc/library/pathlib.rst
+++ b/Doc/library/pathlib.rst
@@ -1054,6 +1054,13 @@ call fails (for example because the path doesn't exist).
    use :func:`Path.rmdir` instead.
 
 
+.. method:: Path.link_to(target)
+
+   Create a hard link pointing to a path named *target*.
+
+   .. versionchanged:: 3.8
+
+
 .. method:: Path.write_bytes(data)
 
    Open the file pointed to in bytes mode, write *data* to it, and close the
diff --git a/Doc/whatsnew/3.8.rst b/Doc/whatsnew/3.8.rst
index 764bd00544d9..64ef6e184060 100644
--- a/Doc/whatsnew/3.8.rst
+++ b/Doc/whatsnew/3.8.rst
@@ -369,6 +369,10 @@ pathlib
 contain characters unrepresentable at the OS level.
 (Contributed by Serhiy Storchaka in :issue:`33721`.)
 
+Added :meth:`pathlib.Path.link_to()` which creates a hard link pointing
+to a path.
+(Contributed by Joannah Nanjekye in :issue:`26978`)
+
 
 socket
 ------
diff --git a/Lib/pathlib.py b/Lib/pathlib.py
index 911b774b5649..1ba98b19e833 100644
--- a/Lib/pathlib.py
+++ b/Lib/pathlib.py
@@ -411,6 +411,8 @@ def lchmod(self, pathobj, mode):
 
     unlink = os.unlink
 
+    link_to = os.link
+
     rmdir = os.rmdir
 
     rename = os.rename
@@ -1303,6 +1305,14 @@ def lstat(self):
             self._raise_closed()
         return self._accessor.lstat(self)
 
+    def link_to(self, target):
+        """
+        Create a hard link pointing to a path named target.
+        """
+        if self._closed:
+            self._raise_closed()
+        self._accessor.link_to(self, target)
+
     def rename(self, target):
         """
         Rename this path to the given path.
diff --git a/Lib/test/test_pathlib.py b/Lib/test/test_pathlib.py
index f8325eb93275..990207b9c4e4 100644
--- a/Lib/test/test_pathlib.py
+++ b/Lib/test/test_pathlib.py
@@ -1643,6 +1643,25 @@ def test_rmdir(self):
         self.assertFileNotFound(p.stat)
         self.assertFileNotFound(p.unlink)
 
+    def test_link_to(self):
+        P = self.cls(BASE)
+        p = P / 'fileA'
+        size = p.stat().st_size
+        # linking to another path.
+        q = P / 'dirA' / 'fileAA'
+        try:
+            p.link_to(q)
+        except PermissionError as e:
+            self.skipTest('os.link(): %s' % e)
+        self.assertEqual(q.stat().st_size, size)
+        self.assertEqual(os.path.samefile(p, q), True)
+        self.assertTrue(p.stat)
+        # Linking to a str of a relative path.
+        r = rel_join('fileAAA')
+        q.link_to(r)
+        self.assertEqual(os.stat(r).st_size, size)
+        self.assertTrue(q.stat)
+
     def test_rename(self):
         P = self.cls(BASE)
         p = P / 'fileA'
diff --git a/Misc/NEWS.d/next/Library/2019-04-28-01-52-39.bpo-26978.Lpm-SI.rst b/Misc/NEWS.d/next/Library/2019-04-28-01-52-39.bpo-26978.Lpm-SI.rst
new file mode 100644
index 000000000000..0b14920ad45a
--- /dev/null
+++ b/Misc/NEWS.d/next/Library/2019-04-28-01-52-39.bpo-26978.Lpm-SI.rst
@@ -0,0 +1,2 @@
+`pathlib.path.link_to()` is now implemented. It creates a hard link pointing
+to a path.