gh-84538: add strict argument to pathlib.PurePath.relative_to #19813

domragusa · 2020-04-30T10:29:59Z

By default, :meth:pathlib.PurePath.relative_to doesn't deal with paths that are not a direct prefix of the other, raising an exception in that instance. This change adds a walk_up parameter that can be set to allow for using .. to calculate the relative path.

example:

>>> p = PurePosixPath('/etc/passwd')
>>> p.relative_to('/etc')
PurePosixPath('passwd')
>>> p.relative_to('/usr')
Traceback (most recent call last):
File "<stdin>", line 1, in <module>
File "pathlib.py", line 940, in relative_to
    raise ValueError(error_message.format(str(self), str(formatted)))
ValueError: '/etc/passwd' does not start with '/usr'
>>> p.relative_to('/usr', strict=False)
PurePosixPath('../etc/passwd')

https://bugs.python.org/issue40358

Automerge-Triggered-By: GH:brettcannon

Issue: pathlib's relative_to should behave like os.path.relpath #84538

Lib/pathlib.py

zeehio · 2020-10-30T06:19:50Z

Thanks! I expected to be able to use relative_to() as described in this PR, I'm happy to know it is being worked on.

Python 3.9 included an is_relative_to() method to PurePath(). Should that method gain a strict argument as well?

domragusa · 2020-10-30T13:25:24Z

I don't know, a is_relative_to with that option would return always true because when you're allowed to traverse the tree structure every path is relative to the other (only exception being when one path is absolute and the other is not or if they are on different discs on windows) anyway if there are useful use cases that I'm missing let me know, I have no problem adding that functionality.

Doc/library/pathlib.rst

terryjreedy · 2021-05-14T22:27:10Z

A what's new entry should go in What's New 3.11.

Co-authored-by: Terry Jan Reedy <tjreedy@udel.edu>

domragusa · 2021-05-15T10:50:59Z

Hi, I'm sorry but I'm not sure about the what's new entry, should I put it under Improved Modules > pathlib? Something like:

pathlib
-------

:meth:`pathlib.PurePath.relative_to` now allows a path that is not a direct
child of the current if the *strict* keyword-only argument is set to False,
the new behavior is more consistent with :meth:`os.relpath`.
(Contributed by Domenico Ragusa in :issue:`40358`.)

barneygale

Looks good - a couple of comments on the docs.

barneygale · 2021-05-17T00:35:20Z

Doc/library/pathlib.rst

+   .. versionadded:: 3.11
+      The *strict* argument (pre-3.11 behavior is strict).
+   .. versionadded:: 3.10
+      The *strict* argument (pre-3.10 behavior is strict).


Duplication?

Oh, I didn't notice this, thanks.

barneygale · 2021-05-17T00:46:30Z

Doc/library/pathlib.rst


-   NOTE: This function is part of :class:`PurePath` and works with strings. It does not check or access the underlying file structure.
+   If the path doesn't start with *other* and *strict* is ``True``, :exc:`ValueError` is raised.  If *strict* is ``False`` and one path is relative and the other is absolute or if they reference different drives :exc:`ValueError` is raised.


I think the key difference should be spelled out in terms of whether adding .. entries is allowed. How about something like this?

In strict mode (the default), the path must start with *other*. In non-strict mode, ``..`` entries may be added to form the relative path. In all other cases, such as the paths referencing different drives, :exe:`ValueError` is raised. .. warning:: Non-strict mode assumes that no symlinks are present in the path; you should call :meth:`~Path.resolve` first to ensure this.

barneygale · 2021-05-17T00:53:21Z

Hi, I'm sorry but I'm not sure about the what's new entry, should I put it under Improved Modules > pathlib? Something like:
pathlib
-------

:meth:`pathlib.PurePath.relative_to` now allows a path that is not a direct
child of the current if the *strict* keyword-only argument is set to False,
the new behavior is more consistent with :meth:`os.relpath`.
(Contributed by Domenico Ragusa in :issue:`40358`.)

This is indeed tricky to phrase! How about:

:meth:`pathlib.PurePath.relative_to` now supports generating relative paths
containing ``..`` entries if its new *strict* keyword-only argument is set to
``False``. The new behavior is more consistent with :func:`os.path.relpath`.
(Contributed by Domenico Ragusa in :issue:`40358`.)

domragusa

@barneygale I've added the what's new entry with the clearer language and fixed the documentation as you suggested. Thanks.

domragusa · 2021-05-17T01:13:10Z

Doc/library/pathlib.rst

+   .. versionadded:: 3.11
+      The *strict* argument (pre-3.11 behavior is strict).
+   .. versionadded:: 3.10
+      The *strict* argument (pre-3.10 behavior is strict).


Oh, I didn't notice this, thanks.

barneygale · 2021-05-17T01:26:01Z

I'm trying to think if there's a better word than 'strict'. In other places, 'strict' usually refers to our behaviour when we get an error from the OS. In this case it's more to do with whether we tolerate the possibility of the path's meaning changing in our pure operation that can't ever raise OSError anyway.

Perhaps something like parents=True to enable the new behaviour, mirroring mkdir()? Or walk_up?

domragusa · 2021-05-18T00:06:47Z

Yeah, strict doesn't give any clue about the actual function. I like walk_up, I'll change it to that tomorrow.

domragusa · 2021-05-29T11:06:47Z

Sorry for the long delay, I just updated the code to follow the suggestion you made about the name of the option.

barneygale · 2021-06-24T10:50:15Z

Doc/library/pathlib.rst

+   When *walk_up* is False, the default, the path must start with *other*,
+   when it's True ``..`` entries may be added to form the relative path. In
+   all other cases, such as the paths referencing different drives,
+   :exc:`ValueError` is raised.


I think this documentation needs to occur before the examples of using walk_up.

So, either move it after "ValueError is raised", or split the examples into two parts.

barneygale · 2021-06-24T10:51:49Z

Aside from a small docs issue, this looks great to me. Really useful feature, nice implementation :)

Others may want to chip in on the naming of walk_up.

CAM-Gerlach · 2021-12-10T21:44:11Z

Hey @domragusa , there has been further interest in this over on the Python discourse; any chance you could tweak the docs, fix the merge conflicts and retrigger the builds?

domragusa · 2022-10-22T02:11:06Z

I have made the requested changes; please review again

bedevere-bot · 2022-10-22T02:11:10Z

Thanks for making the requested changes!

@brettcannon: please review the changes made to this pull request.

Doc/library/pathlib.rst

miss-islington · 2022-10-28T22:56:56Z

@domragusa: Status check is done, and it's a failure or timed out ❌.

domragusa · 2022-10-28T23:02:20Z

I'm not sure I understand the last comment, what status check has failed? Should I do anything else?

miss-islington · 2022-10-28T23:20:13Z

Status check is done, and it's a success ✅.

brettcannon · 2022-10-28T23:32:13Z

@domragusa thanks so much for your patience with this!

domragusa · 2022-10-28T23:40:16Z

I'm very happy to see this being merged, thanks to @brettcannon and everyone else who helped along the way :)

ctismer · 2022-10-29T12:34:06Z

Maybe I‘m misunderstanding, but this was an incompatibility to path.relpath which is now fixed. Should it not be considered a bug, and the fix be back-ported to a few versions?

domragusa · 2022-10-29T17:29:34Z

I don't think anybody is currently relying on pathlib for this behaviour, in fact when I looked around for anwsers they were generally saying to use os.path.relpath and also the original developer told me it was the intended behaviour (see #84538), so I'm not convinced we should consider it as a bug.

Anyway, if there are specific arguments for backporting it's fine by me.

ctismer · 2022-10-31T15:07:58Z

Ok, the table at the end of the pathlib doc was augmented, and relpath was listed with a comment.
You are right, it is not a bug. Still, we were trying to convert everything, but this is the only function that has no equivalent at os.path, and it would take quite long until this change makes it through our supported versions from 3.7 on :)

zeehio · 2022-10-31T20:49:23Z

Hi

With respect to the backporting, I took this pull request and created a small package out of it, following the backports package guidelines.

I included some of the tests.

https://pypi.org/project/backports-pathlib-relative-to/0.1.0/

https://github.com/zeehio/backports-pathlib-relative-to

Issues and pull requests are welcome

barneygale · 2022-11-03T17:24:00Z

FYI, I've opened a bug and PR to address one final incompatibility between PurePath.relative_to() and os.path.relpath().

bpo-40358: add strict param to pathlib.PurePath.relative_to

ec64368

the-knights-who-say-ni added the CLA signed label Apr 30, 2020

bedevere-bot added the awaiting review label Apr 30, 2020

domragusa mentioned this pull request Apr 30, 2020

bpo-40358: add strict parameter to pathlib.PurePath.relative_to #19807

Closed

CuriousLearner reviewed Apr 30, 2020

View reviewed changes

Lib/pathlib.py Show resolved Hide resolved

resolve conflicts with pythonGH-19611

6d721a0

domragusa changed the title ~~bpo-40358: add strict param to pathlib.PurePath.relative_to~~ bpo-40358: add strict argument to pathlib.PurePath.relative_to May 28, 2020

zeehio mentioned this pull request Oct 30, 2020

Add fs.relative_to() function. Closes #2184 mesonbuild/meson#7908

Closed

terryjreedy reviewed May 14, 2021

View reviewed changes

Doc/library/pathlib.rst Outdated Show resolved Hide resolved

domragusa and others added 2 commits May 15, 2021 12:26

Merge branch 'python:main' into relative_to_strict_param

09422e7

Update Doc/library/pathlib.rst

d9c07c2

Co-authored-by: Terry Jan Reedy <tjreedy@udel.edu>

barneygale reviewed May 17, 2021

View reviewed changes

fix wording in documentation as requested

029c3d5

domragusa commented May 17, 2021

View reviewed changes

fix typo

01e789b

change strict argument to walk_up in pathlib.PurePath.relative_to

39b24f3

barneygale reviewed Jun 24, 2021

View reviewed changes

brettcannon added the topic-pathlib label Jun 21, 2022

domragusa mannequin mentioned this pull request Jun 21, 2022

pathlib's relative_to should behave like os.path.relpath #84538

Closed

ezio-melotti removed the CLA signed label Jul 13, 2022

domragusa and others added 3 commits October 22, 2022 02:49

improve variable names

8a4edb5

remove trailing spaces

e6cf222

Merge branch 'main' into relative_to_strict_param

b8b218c

bedevere-bot added awaiting change review and removed awaiting changes labels Oct 22, 2022

bedevere-bot requested a review from brettcannon October 22, 2022 02:11

brettcannon approved these changes Oct 28, 2022

View reviewed changes

Doc/library/pathlib.rst Outdated Show resolved Hide resolved

bedevere-bot added awaiting merge and removed awaiting change review labels Oct 28, 2022

brettcannon added 2 commits October 28, 2022 15:54

Update Doc/library/pathlib.rst

a4c77c2

Merge branch 'main' into relative_to_strict_param

97a5e22

brettcannon added the 🤖 automerge label Oct 28, 2022

brettcannon changed the title ~~bpo-40358: add strict argument to pathlib.PurePath.relative_to~~ gh-84538: add strict argument to pathlib.PurePath.relative_to Oct 28, 2022

miss-islington merged commit e089f23 into python:main Oct 28, 2022

bedevere-bot removed the awaiting merge label Oct 28, 2022

h-mayorquin mentioned this pull request Jul 17, 2023

Allow relative_to with recursive=False (in-place on objects) SpikeInterface/spikeinterface#1824

Closed

dundargoc mentioned this pull request Dec 30, 2024

feat: add vim.fs.relpath neovim/neovim#31790

Merged

sholderbach mentioned this pull request Apr 22, 2025

Allow path relative-to to use parent directory symbols nushell/nushell#14055

Open

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

gh-84538: add strict argument to pathlib.PurePath.relative_to #19813

gh-84538: add strict argument to pathlib.PurePath.relative_to #19813

domragusa commented Apr 30, 2020 •

edited by bedevere-bot

Loading

zeehio commented Oct 30, 2020

domragusa commented Oct 30, 2020 via email •

edited

Loading

terryjreedy commented May 14, 2021

domragusa commented May 15, 2021

barneygale left a comment

barneygale May 17, 2021

domragusa May 17, 2021

barneygale May 17, 2021

barneygale commented May 17, 2021

domragusa left a comment

domragusa May 17, 2021

barneygale commented May 17, 2021

domragusa commented May 18, 2021

domragusa commented May 29, 2021

barneygale Jun 24, 2021

barneygale commented Jun 24, 2021

CAM-Gerlach commented Dec 10, 2021

domragusa commented Oct 22, 2022

bedevere-bot commented Oct 22, 2022

miss-islington commented Oct 28, 2022

domragusa commented Oct 28, 2022

miss-islington commented Oct 28, 2022

brettcannon commented Oct 28, 2022

domragusa commented Oct 28, 2022

ctismer commented Oct 29, 2022 •

edited

Loading

domragusa commented Oct 29, 2022 •

edited

Loading

ctismer commented Oct 31, 2022

zeehio commented Oct 31, 2022

barneygale commented Nov 3, 2022


		NOTE: This function is part of :class:`PurePath` and works with strings. It does not check or access the underlying file structure.
		If the path doesn't start with other and strict is ``True``, :exc:`ValueError` is raised. If strict is ``False`` and one path is relative and the other is absolute or if they reference different drives :exc:`ValueError` is raised.

gh-84538: add strict argument to pathlib.PurePath.relative_to #19813

gh-84538: add strict argument to pathlib.PurePath.relative_to #19813

Conversation

domragusa commented Apr 30, 2020 • edited by bedevere-bot Loading

zeehio commented Oct 30, 2020

domragusa commented Oct 30, 2020 via email • edited Loading

terryjreedy commented May 14, 2021

domragusa commented May 15, 2021

barneygale left a comment

Choose a reason for hiding this comment

barneygale May 17, 2021

Choose a reason for hiding this comment

domragusa May 17, 2021

Choose a reason for hiding this comment

barneygale May 17, 2021

Choose a reason for hiding this comment

barneygale commented May 17, 2021

domragusa left a comment

Choose a reason for hiding this comment

domragusa May 17, 2021

Choose a reason for hiding this comment

barneygale commented May 17, 2021

domragusa commented May 18, 2021

domragusa commented May 29, 2021

barneygale Jun 24, 2021

Choose a reason for hiding this comment

barneygale commented Jun 24, 2021

CAM-Gerlach commented Dec 10, 2021

domragusa commented Oct 22, 2022

bedevere-bot commented Oct 22, 2022

miss-islington commented Oct 28, 2022

domragusa commented Oct 28, 2022

miss-islington commented Oct 28, 2022

brettcannon commented Oct 28, 2022

domragusa commented Oct 28, 2022

ctismer commented Oct 29, 2022 • edited Loading

domragusa commented Oct 29, 2022 • edited Loading

ctismer commented Oct 31, 2022

zeehio commented Oct 31, 2022

barneygale commented Nov 3, 2022

domragusa commented Apr 30, 2020 •

edited by bedevere-bot

Loading

domragusa commented Oct 30, 2020 via email •

edited

Loading

ctismer commented Oct 29, 2022 •

edited

Loading

domragusa commented Oct 29, 2022 •

edited

Loading