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

5 files changed, 42 insertions, 0 deletions

diff --git a/Doc/library/pathlib.rst b/Doc/library/pathlib.rst
index 450e8ff..7a4a20d 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 764bd00..64ef6e1 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 911b774..1ba98b1 100644
--- a/Lib/pathlib.py
+++ b/Lib/pathlib.py
@@ -411,6 +411,8 @@ class _NormalAccessor(_Accessor):
 
     unlink = os.unlink
 
+    link_to = os.link
+
     rmdir = os.rmdir
 
     rename = os.rename
@@ -1303,6 +1305,14 @@ class Path(PurePath):
             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 f8325eb..990207b 100644
--- a/Lib/test/test_pathlib.py
+++ b/Lib/test/test_pathlib.py
@@ -1643,6 +1643,25 @@ class _BasePathTest(object):
         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 0000000..0b14920
--- /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.