[docs] [issue34526] Path.relative_to() taking multiple arguments could be better documented

Antony Lee report at bugs.python.org
Tue Aug 28 04:42:29 EDT 2018

New submission from Antony Lee <anntzer.lee at gmail.com>:

Currently, the docs for Path.relative_to read

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

assignee: docs at python
components: Documentation
messages: 324224
nosy: Antony.Lee, docs at python
priority: normal
severity: normal
status: open
title: Path.relative_to() taking multiple arguments could be better documented
versions: Python 3.7

Python tracker <report at bugs.python.org>

More information about the docs mailing list