Path.relative_to() taking multiple arguments could be better documented

@anntzer

BPO	34526
Nosy	@anntzer, @barneygale
PRs	bpo-34526：[doc] Add description and examples of multiple arguments for Path.relative_to #31368

^{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']

Linked PRs

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

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.

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

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

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

Navigation Menu

Repository navigation

Path.relative_to() taking multiple arguments could be better documented #78707

Linked PRs

Metadata

Assignees

Labels

Projects

Milestone

Relationships

Development

Path.relative_to() taking multiple arguments could be better documented #78707

Description

Linked PRs

Activity

anntzer commented on Aug 28, 2018

barneygale commented on May 2, 2022

JelleZijlstra commented on May 2, 2022

Metadata

Metadata

Assignees

Labels

Projects

Milestone

Relationships

Development

Issue actions