Why does Python pathlib relative_to allow multiple input paths?

Question

Why is *other used here. What does it mean if multiple paths are passed in?

PurePath.relative_to(*other)

https://docs.python.org/3/library/pathlib.html#pathlib.PurePath.relative_to

It seems only the last one matters

In [1]: p = Path('/etc/pass')
[PYFLYBY] from pathlib import Path

In [2]: p.relative_to('arsta', '/etc', '/etc')
Out[2]: PosixPath('pass')

In [3]: p.relative_to('arsta', '/etc', '/etc/')
Out[3]: PosixPath('pass')

In [4]: p.relative_to('arsta', '/etc', '/etc/arstar')
---------------------------------------------------------------------------
ValueError                                Traceback (most recent call last)
<ipython-input-4-1669e7092659> in <module>
----> 1 p.relative_to('arsta', '/etc', '/etc/arstar')

/opt/schrodinger/suites2022-1/internal/lib/python3.8/pathlib.py in relative_to(self, *other)
    906         if (root or drv) if n == 0 else cf(abs_parts[:n]) != cf(to_abs_parts):
    907             formatted = self._format_parsed_parts(to_drv, to_root, to_parts)
--> 908             raise ValueError("{!r} does not start with {!r}"
    909                              .format(str(self), str(formatted)))
    910         return self._from_parsed_parts('', root if n == 1 else '',

ValueError: '/etc/pass' does not start with '/etc/arstar'

Additional test cases

In [8]: p.relative_to('/etc', 'pass')
Out[8]: PosixPath('.')

In [9]: p.relative_to('axx', '/etc', 'pass')
Out[9]: PosixPath('.')

In [10]: p.relative_to('/axx', '/etc', 'pass')
Out[10]: PosixPath('.')

Maybe the intended usage is ['/etc', 'pass']? How would one transform back and forth between this valid list form and /etc/pass?

Answer 1

Yes the intention is to allow specifying paths from separate parts, without needing to use a (platform-dependent) path separator.

This is clear from the test suite (src):

def test_relative_to_common(self):
    P = self.cls
    p = P('a/b')
    ...
    self.assertEqual(p.relative_to('a/b'), P())
    # With several args.
    self.assertEqual(p.relative_to('a', 'b'), P())

And it is also analogous to other interfaces in pathlib which accept *args, for example:

>>> Path("/usr").joinpath("local", "bin")
PosixPath('/usr/local/bin')
>>> Path(".").joinpath("a", "b", "c")
PosixPath('a/b/c')
>>> Path(Path.home(), "music", "mp3s")
PosixPath('/home/wim/music/mp3s')