Repository navigation
Path.relative_to() taking multiple arguments could be better documented #78707
Description
| BPO | 34526 |
|---|---|
| Nosy | @anntzer, @barneygale |
| PRs |
Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.
Show more details
GitHub fields:
assignee = None
closed_at = None
created_at = <Date 2018-08-28.08:42:29.205>
labels = ['easy', '3.11', '3.9', '3.10', 'docs']
title = 'Path.relative_to() taking multiple arguments could be better documented'
updated_at = <Date 2022-02-16.08:01:06.637>
user = 'https://github.com/anntzer'bugs.python.org fields:
activity = <Date 2022-02-16.08:01:06.637>
actor = 'python-dev'
assignee = 'docs@python'
closed = False
closed_date = None
closer = None
components = ['Documentation']
creation = <Date 2018-08-28.08:42:29.205>
creator = 'Antony.Lee'
dependencies = []
files = []
hgrepos = []
issue_num = 34526
keywords = ['patch', 'easy']
message_count = 1.0
messages = ['324224']
nosy_count = 4.0
nosy_names = ['docs@python', 'python-dev', 'Antony.Lee', 'barneygale']
pr_nums = ['31368']
priority = 'normal'
resolution = None
stage = 'patch review'
status = 'open'
superseder = None
type = None
url = 'https://bugs.python.org/issue34526'
versions = ['Python 3.9', 'Python 3.10', 'Python 3.11']
Activity
anntzer commentedon Aug 28, 2018
Currently, the docs for Path.relative_to read
It's a bit confusing why other is a star-args, especially as no example actually passes more than one argument to relative_to.
The docstring is a tiny bit clearer:
Effectively, a Path is constructed from all *other args and used as base for the computation of the relative path. It looks a bit like a misfeature to me, but at least it could be better documented (e.g. by adding
Path("/tmp/foo/bar").relative_to("/tmp", "foo") == Path("bar")as example in the docs).barneygale commentedon May 2, 2022
I think this is a mis-feature and we should look at deprecating + removing it, rather than documenting it.
Consider that pathlib has many other methods that accept a single other path, like
rename(),replace(),symlink_to()andhardlink_to().The only methods that should support
*argsshould bejoinpath()and thePurePathinitialiser IMO.JelleZijlstra commentedon May 2, 2022
Agree that this is a misfeature. We'll have to go through a deprecation cycle to remove it though, since it's at least kind of documented.
Merge branch 'main' into pythongh-78707-pathlib-relative-to-arguments
gh-78707: deprecate passing >1 argument to `PurePath.[is_]relative_to…
Merge remote-tracking branch 'origin/main' into bpo_34697
Merge branch 'main' into fastmock
pythonGH-78707: Drop deprecated `pathlib.PurePath.[is_]relative_to()`…
Merge branch 'main' into pythongh-78707-remove
Merge branch 'main' into pythongh-78707-remove
GH-78707: Drop deprecated `pathlib.PurePath.[is_]relative_to()` argum…
pythonGH-78707: Drop deprecated `pathlib.PurePath.[is_]relative_to()`…