bpo-42999: Expand and clarify pathlib.Path.link_to() documentation. (GH-24294)

Co-authored-by: Barney Gale <barney.gale@gmail.com>

diff --git a/Doc/library/pathlib.rst b/Doc/library/pathlib.rst
index 4518f56004929ca6c58c6ec8be0813e4b588df6e..1aae59610c7f7cded2eda7a3166497fd2f0dcdb8 100644 (file)
--- a/Doc/library/pathlib.rst
+++ b/Doc/library/pathlib.rst
@@ -1063,6 +1063,20 @@ call fails (for example because the path doesn't exist).
       of :func:`os.symlink`'s.
 
 
+.. method:: Path.link_to(target)
+
+   Make *target* a hard link to this path.
+
+   .. warning::
+
+      This function does not make this path a hard link to *target*, despite
+      the implication of the function and argument names. The argument order
+      (target, link) is the reverse of :func:`Path.symlink_to`, but matches
+      that of :func:`os.link`.
+
+   .. versionadded:: 3.8
+
+
 .. method:: Path.touch(mode=0o666, exist_ok=True)
 
    Create a file at this given path.  If *mode* is given, it is combined
@@ -1087,13 +1101,6 @@ call fails (for example because the path doesn't exist).
       The *missing_ok* parameter was added.
 
 
-.. method:: Path.link_to(target)
-
-   Create a hard link pointing to a path named *target*.
-
-   .. versionadded:: 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/Lib/pathlib.py b/Lib/pathlib.py
index 171d8b825210697fb1cffb7392806235fc41021d..5e3940bccc8ffbb6fb4410d28cc8795ba4bae936 100644 (file)
--- a/Lib/pathlib.py
+++ b/Lib/pathlib.py
@@ -1343,14 +1343,6 @@ 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 target path.
@@ -1383,13 +1375,27 @@ class Path(PurePath):
 
     def symlink_to(self, target, target_is_directory=False):
         """
-        Make this path a symlink pointing to the given path.
-        Note the order of arguments (self, target) is the reverse of os.symlink's.
+        Make this path a symlink pointing to the target path.
+        Note the order of arguments (link, target) is the reverse of os.symlink.
         """
         if self._closed:
             self._raise_closed()
         self._accessor.symlink(target, self, target_is_directory)
 
+    def link_to(self, target):
+        """
+        Make the target path a hard link pointing to this path.
+
+        Note this function does not make this path a hard link to *target*,
+        despite the implication of the function and argument names. The order
+        of arguments (target, link) is the reverse of Path.symlink_to, but
+        matches that of os.link.
+
+        """
+        if self._closed:
+            self._raise_closed()
+        self._accessor.link_to(self, target)
+
     # Convenience functions for querying the stat results
 
     def exists(self):