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()`.

1 files changed, 15 insertions, 0 deletions

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 os
 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 @@ class Path(PurePath):
         """
         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 @@ class Path(PurePath):
         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