Description

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'

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

1. anntzer commented on Aug 28, 2018

   

   anntzermannequin

   on Aug 28, 2018

   MannequinAuthor

   More actions

   Currently, the docs for Path.relative_to read

       PurePath.relative_to(*other)
       Compute a version of this path relative to the path represented by other. If it’s impossible, ValueError is raised: (examples follow)

   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:

   Return the relative path to another path identified by the passed
   arguments.  If the operation is not possible (because this is not
   a subpath of the other path), raise ValueError.
   

   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).
2. anntzer

   added

   3.7 (EOL)end of lifeend of life

   on Aug 28, 2018
3. anntzer

   assigned

   docspython

   on Aug 28, 2018
4. anntzer

   added

   docsDocumentation in the Doc dirDocumentation in the Doc dir

   on Aug 28, 2018
5. iritkatriel

   added

   easy

   3.9 (EOL)end of lifeend of life

   3.10 (EOL)end of lifeend of life

   3.11only security fixesonly security fixes

   and removed

   3.7 (EOL)end of lifeend of life

   on Jan 19, 2022
6. ezio-melotti

   transferred this issue fromon Apr 10, 2022
7. barneygale commented on May 2, 2022

   

   barneygale

   on May 2, 2022

   Contributor

   More actions

   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() and hardlink_to().

   The only methods that should support *args should be joinpath() and the PurePath initialiser IMO.

   Reacted by Jelle Zijlstra
8. JelleZijlstra commented on May 2, 2022

   

   JelleZijlstra

   on May 2, 2022

   Member

   More actions

   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.

   Reacted by Barney Gale
9. barneygale

   added a commit that references this issue on Nov 25, 2022

   Merge branch 'main' into pythongh-78707-pathlib-relative-to-arguments

   0e79a85
10. miss-islington

    closed this as completedin #94469on Dec 17, 2022
11. miss-islington

    added a commit that references this issue on Dec 17, 2022

    gh-78707: deprecate passing >1 argument to `PurePath.[is_]relative_to…

    5a991da
12. shihai1991

    added a commit that references this issue on Dec 18, 2022

    Merge remote-tracking branch 'origin/main' into bpo_34697

    2878571
13. carljm

    added a commit that references this issue on Dec 19, 2022

    Merge branch 'main' into fastmock

    a9af20a
14. barneygale

    added 4 commits that reference this issue on May 8, 2024

    pythonGH-78707: Drop deprecated `pathlib.PurePath.[is_]relative_to()`…

    a3db1b9

    Merge branch 'main' into pythongh-78707-remove

    0be21b1

    Merge branch 'main' into pythongh-78707-remove

    ececcd9

    GH-78707: Drop deprecated `pathlib.PurePath.[is_]relative_to()` argum…

    f772d0d
15. estyxx

    added a commit that references this issue on Jul 17, 2024

    pythonGH-78707: Drop deprecated `pathlib.PurePath.[is_]relative_to()`…

    17dec15

Issue actions