Title: Add pathlib.Path.hardlink_to()
Type: enhancement Stage: patch review
Components: Library (Lib) Versions: Python 3.9
Status: open Resolution:
Dependencies: Superseder:
Assigned To: Nosy List: barneygale, escape0707
Priority: normal Keywords: patch

Created on 2020-03-13 00:50 by barneygale, last changed 2021-01-22 04:26 by barneygale.

Pull Requests
URL Status Linked Edit
PR 18909 open barneygale, 2020-03-13 00:50
Messages (6)
msg364060 - (view) Author: Barney Gale (barneygale) * Date: 2020-03-13 00:50
Per bpo-39291, the argument order for `pathlib.Path.link_to()` is inconsistent with `symlink_to()` and its own documentation.

This ticket covers adding a new `hardlink_to()` method with the correct argument order, and deprecating `link_to()`.

Discussion on python-dev:
msg365275 - (view) Author: Barney Gale (barneygale) * Date: 2020-03-29 19:52
A question:

For my patch, I need to include a Python version where `Path.link_to()` will become unavailable. I'm not entirely sure how this should be determined. Some factors in play:

- `link_to()` was added in Python 3.8
- On github, I found these three repos which use `link_to()`:

Can anyone suggest in which version of Python this function should be removed? Thanks.
msg385199 - (view) Author: Jay Chu (escape0707) Date: 2021-01-18 14:42
Maybe we could have the correct `Path.hardlink` implemented before removing or even deprecating the confusing `Path.link_to`? It will only help even if we don't remove the latter in a hurry.
msg385458 - (view) Author: Barney Gale (barneygale) * Date: 2021-01-21 23:56
Makes sense to me. Should I leave the documentation for `link_to` completely alone? With the addition of a similar function, I wonder if that may in itself cause confusion.
msg385471 - (view) Author: Jay Chu (escape0707) Date: 2021-01-22 03:40
For me, and as you've pointed out, the current doc of `Path.link_to` is already wrong and misleading. Perhaps a fix of the doc should be made as a first step.

The doc uses the expression "Create a hard link pointing to a path named target." 
But comparing this to the doc of `Path.symlink_to`, which says "Make this path a symbolic link to target.", 
(and the doc of ``, which says, "Create a hard link pointing to src named dst.",)
the current doc should actually be "Create a hard link at `target` pointing to this path." Sadly the argument name can't be changed here already.

And the doc of `Path.symlink_to` even have a helpful note: "Note: The order of arguments (link, target) is the reverse of os.symlink()’s." 
We could also add one for `Path.link_to`, too, like "Note: The order of arguments (link, target) is the consistent with’s.

Based on that foundation, we could finally continue to implement the correct "Path.hardlink_to". 

We can refer to how people retained `` while adding a newer , preferred ``, by noting people to prefer `Path.hardlink_to` as it's more consistent with the `pathlib` and OOP, along with telling them the obscurity of `Path.link_to` and why it's left here for backward capability.
msg385475 - (view) Author: Barney Gale (barneygale) * Date: 2021-01-22 04:26
I've logged bpo-42999 to cover fixing the existing `link_to()` docs issues. PR incoming...
Date User Action Args
2021-01-22 04:26:32barneygalesetmessages: + msg385475
2021-01-22 03:40:31escape0707setmessages: + msg385471
2021-01-21 23:56:50barneygalesetmessages: + msg385458
2021-01-18 14:42:44escape0707setnosy: + escape0707
messages: + msg385199
2020-03-29 19:52:43barneygalesetmessages: + msg365275
2020-03-13 00:50:57barneygalesetkeywords: + patch
stage: patch review
pull_requests: + pull_request18321
2020-03-13 00:50:05barneygalecreate