bpo-39950: add `pathlib.Path.hardlink_to()` method that supersedes `link_to()` (GH-18909)
The argument order of `link_to()` is reversed compared to what one may expect, so:
a.link_to(b)
Might be expected to create *a* as a link to *b*, in fact it creates *b* as a link to *a*, making it function more like a "link from". This doesn't match `symlink_to()` nor the documentation and doesn't seem to be the original author's intent.
This PR deprecates `link_to()` and introduces `hardlink_to()`, which has the same argument order as `symlink_to()`.diff --git a/Lib/pathlib.py b/Lib/pathlib.py
index ebc2c02..37934c6 100644
--- a/Lib/pathlib.py
+++ b/Lib/pathlib.py
@@ -6,6 +6,7 @@
import posixpath
import re
import sys
+import warnings
from _collections_abc import Sequence
from errno import EINVAL, ENOENT, ENOTDIR, EBADF, ELOOP
from operator import attrgetter
@@ -1306,6 +1307,14 @@ def symlink_to(self, target, target_is_directory=False):
"""
self._accessor.symlink(target, self, target_is_directory)
+ def hardlink_to(self, target):
+ """
+ Make this path a hard link pointing to the same file as *target*.
+
+ Note the order of arguments (self, target) is the reverse of os.link's.
+ """
+ self._accessor.link(target, self)
+
def link_to(self, target):
"""
Make the target path a hard link pointing to this path.
@@ -1315,7 +1324,13 @@ def link_to(self, target):
of arguments (target, link) is the reverse of Path.symlink_to, but
matches that of os.link.
+ Deprecated since Python 3.10 and scheduled for removal in Python 3.12.
+ Use `hardlink_to()` instead.
"""
+ warnings.warn("pathlib.Path.link_to() is deprecated and is scheduled "
+ "for removal in Python 3.12. "
+ "Use pathlib.Path.hardlink_to() instead.",
+ DeprecationWarning)
self._accessor.link(self, target)
# Convenience functions for querying the stat results
diff --git a/Lib/test/test_pathlib.py b/Lib/test/test_pathlib.py
index 0c89b6e..6ed08f7 100644
--- a/Lib/test/test_pathlib.py
+++ b/Lib/test/test_pathlib.py
@@ -1925,7 +1925,8 @@ def test_link_to(self):
# linking to another path.
q = P / 'dirA' / 'fileAA'
try:
- p.link_to(q)
+ with self.assertWarns(DeprecationWarning):
+ p.link_to(q)
except PermissionError as e:
self.skipTest('os.link(): %s' % e)
self.assertEqual(q.stat().st_size, size)
@@ -1937,6 +1938,24 @@ def test_link_to(self):
self.assertEqual(os.stat(r).st_size, size)
self.assertTrue(q.stat)
+ @unittest.skipUnless(hasattr(os, "link"), "os.link() is not present")
+ def test_hardlink_to(self):
+ P = self.cls(BASE)
+ target = P / 'fileA'
+ size = target.stat().st_size
+ # linking to another path.
+ link = P / 'dirA' / 'fileAA'
+ link.hardlink_to(target)
+ self.assertEqual(link.stat().st_size, size)
+ self.assertTrue(os.path.samefile(target, link))
+ self.assertTrue(target.exists())
+ # Linking to a str of a relative path.
+ link2 = P / 'dirA' / 'fileAAA'
+ target2 = rel_join('fileA')
+ link2.hardlink_to(target2)
+ self.assertEqual(os.stat(target2).st_size, size)
+ self.assertTrue(link2.exists())
+
@unittest.skipIf(hasattr(os, "link"), "os.link() is present")
def test_link_to_not_implemented(self):
P = self.cls(BASE)