bpo-42999: Expand and clarify pathlib.Path.link_to() documentation. (GH-24294)
diff --git a/Doc/library/pathlib.rst b/Doc/library/pathlib.rst
index b1cfbed..e269bf9 100644
--- a/Doc/library/pathlib.rst
+++ b/Doc/library/pathlib.rst
@@ -1134,6 +1134,20 @@
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
@@ -1158,13 +1172,6 @@
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 eaaf980..6838fea 100644
--- a/Lib/pathlib.py
+++ b/Lib/pathlib.py
@@ -1315,12 +1315,6 @@ def lstat(self):
"""
return self.stat(follow_symlinks=False)
- def link_to(self, target):
- """
- Create a hard link pointing to a path named target.
- """
- self._accessor.link(self, target)
-
def rename(self, target):
"""
Rename this path to the target path.
@@ -1349,11 +1343,23 @@ def replace(self, target):
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.
"""
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.
+
+ """
+ self._accessor.link(self, target)
+
# Convenience functions for querying the stat results
def exists(self):