gh-84538: add strict argument to pathlib.PurePath.relative_to by domragusa · Pull Request #19813 · python/cpython · GitHub

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

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?

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.

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

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

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

Looks good - a couple of comments on the docs.

Duplication?

Oh, I didn't notice this, thanks.

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.

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

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

Oh, I didn't notice this, thanks.

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?

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

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

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.

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.

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?

I have made the requested changes; please review again

Thanks for making the requested changes!

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

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

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

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

@domragusa thanks so much for your patience with this!

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

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?

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.

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

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

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

Comment thread Lib/pathlib.py

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

Comment thread Doc/library/pathlib.rst Outdated

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

Comment thread Doc/library/pathlib.rst Outdated

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

Closed

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

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

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

+                    ValueError: '/etc/passwd' is not on the same drive as 'foo' OR one path is relative and the other is absolute.
-                 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 by domragusa · Pull Request #19813 · python/cpython · GitHub

Uh oh!

Uh oh!

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

gh-84538: add strict argument to pathlib.PurePath.relative_to#19813miss-islington merged 17 commits intopython:mainpython/cpython:mainfrom domragusa:relative_to_strict_paramdomragusa/cpython:relative_to_strict_paramCopy head branch name to clipboard

Conversation

domragusa commented Apr 30, 2020 • edited by bedevere-bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

zeehio commented Oct 30, 2020

Uh oh!

domragusa commented Oct 30, 2020 via email • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

terryjreedy commented May 14, 2021

Uh oh!

domragusa commented May 15, 2021

Uh oh!

barneygale left a comment

Choose a reason for hiding this comment

Uh oh!

barneygale May 17, 2021

Choose a reason for hiding this comment

Uh oh!

domragusa May 17, 2021

Choose a reason for hiding this comment

Uh oh!

barneygale May 17, 2021

Choose a reason for hiding this comment

Uh oh!

barneygale commented May 17, 2021

Uh oh!

domragusa left a comment

Choose a reason for hiding this comment

Uh oh!

domragusa May 17, 2021

Choose a reason for hiding this comment

Uh oh!

barneygale commented May 17, 2021

Uh oh!

domragusa commented May 18, 2021

Uh oh!

domragusa commented May 29, 2021

Uh oh!

barneygale Jun 24, 2021

Choose a reason for hiding this comment

Uh oh!

barneygale commented Jun 24, 2021

Uh oh!

CAM-Gerlach commented Dec 10, 2021

Uh oh!

domragusa commented Oct 22, 2022

Uh oh!

bedevere-bot commented Oct 22, 2022

Uh oh!

Uh oh!

miss-islington commented Oct 28, 2022

Uh oh!

domragusa commented Oct 28, 2022

Uh oh!

miss-islington commented Oct 28, 2022

Uh oh!

brettcannon commented Oct 28, 2022

Uh oh!

domragusa commented Oct 28, 2022

Uh oh!

ctismer commented Oct 29, 2022 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

domragusa commented Oct 29, 2022 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

ctismer commented Oct 31, 2022

Uh oh!

zeehio commented Oct 31, 2022

Uh oh!

barneygale commented Nov 3, 2022

Uh oh!

gh-84538: add strict argument to pathlib.PurePath.relative_to#19813
miss-islington merged 17 commits into
python:mainfrom
domragusa:relative_to_strict_param

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