New submission from Antony Lee <anntzer.lee@gmail.com>: 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). ---------- assignee: docs@python components: Documentation messages: 324224 nosy: Antony.Lee, docs@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@bugs.python.org> <https://bugs.python.org/issue34526> _______________________________________