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/Doc/library/pathlib.rst b/Doc/library/pathlib.rst
index 122642a..b6507eb 100644
--- a/Doc/library/pathlib.rst
+++ b/Doc/library/pathlib.rst
@@ -1140,6 +1140,15 @@
The order of arguments (link, target) is the reverse
of :func:`os.symlink`'s.
+.. method:: Path.hardlink_to(target)
+
+ Make this path a hard link to the same file as *target*.
+
+ .. note::
+ The order of arguments (link, target) is the reverse
+ of :func:`os.link`'s.
+
+ .. versionadded:: 3.10
.. method:: Path.link_to(target)
@@ -1149,11 +1158,17 @@
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`.
+ (target, link) is the reverse of :func:`Path.symlink_to` and
+ :func:`Path.hardlink_to`, but matches that of :func:`os.link`.
.. versionadded:: 3.8
+ .. deprecated:: 3.10
+
+ This method is deprecated in favor of :meth:`Path.hardlink_to`, as the
+ argument order of :meth:`Path.link_to` does not match that of
+ :meth:`Path.symlink_to`.
+
.. method:: Path.touch(mode=0o666, exist_ok=True)
@@ -1246,7 +1261,7 @@
:func:`os.path.isdir` :meth:`Path.is_dir`
:func:`os.path.isfile` :meth:`Path.is_file`
:func:`os.path.islink` :meth:`Path.is_symlink`
-:func:`os.link` :meth:`Path.link_to`
+:func:`os.link` :meth:`Path.hardlink_to`
:func:`os.symlink` :meth:`Path.symlink_to`
:func:`os.readlink` :meth:`Path.readlink`
:func:`os.path.relpath` :meth:`Path.relative_to` [#]_
diff --git a/Doc/whatsnew/3.10.rst b/Doc/whatsnew/3.10.rst
index 86cf11f..247749a 100644
--- a/Doc/whatsnew/3.10.rst
+++ b/Doc/whatsnew/3.10.rst
@@ -1007,6 +1007,11 @@
<pathlib.PurePath.parents>`.
(Contributed by Yaroslav Pankovych in :issue:`21041`)
+Added :meth:`Path.hardlink_to <pathlib.Path.hardlink_to>` method that
+supersedes :meth:`~pathlib.Path.link_to`. The new method has the same argument
+order as :meth:`~pathlib.Path.symlink_to`.
+(Contributed by Barney Gale in :issue:`39950`.)
+
platform
--------
@@ -1363,6 +1368,10 @@
(Contributed by Jelle Zijlstra in :issue:`21574`.)
+* :meth:`pathlib.Path.link_to` is deprecated and slated for removal in
+ Python 3.12. Use :meth:`pathlib.Path.hardlink_to` instead.
+ (Contributed by Barney Gale in :issue:`39950`.)
+
Removed
=======