Fix pip-compile handling of -r paths which are not subpaths of the cwd

[sirosen]

resolves #2231

When -r is used to pass a path, we are normalizing with pathlib.Path.relative_to. This fails when the input is not a subpath of the current working directory.

In Python 3.12+ pathlib supports this usage (walk_up=True), but on older Pythons we need to fallback to using os.path.relpath.

In order to support this usage and give a clear indication of how we should upgrade when older versions are dropped, a small compat wrapper is here defined, _relative_to_walk_up which uses relative_to(..., walk_up=True) when it is available, and only uses os.path.relpath when necessary. After we drop Python 3.11 in a few years, the helper can be removed.

A new regression test reproduces #2231 and is fixed with this patch.
As part of writing that test, I wanted to leverage the TestFilesCollection helper, so this was extended in a small way to support usage without an explicit name.

Contributor checklist

• Included tests for the changes.
• A change note is created in changelog.d/ (see changelog.d/README.md for instructions) or the PR text says "no changelog needed".

Maintainer checklist

• If no changelog is needed, apply the skip-changelog label.
• Assign the PR to an existing or new milestone for the target version (following Semantic Versioning).

[webknjaz]

non-imperative mood plz

[sirosen]

I need to break this habit of writing changelogs like commit messages. I even updated docs at work to remind people to use past tense for changelogs, and then I go around forgetting it myself! 😆

Thanks for the save.

[webknjaz]

I wonder if we can get an LLM help out with this. I've been looking into configuring some LLM behaviors (CLAUDE.md / AGENTS.md) recently and this should be a func exercise.. Although, we could probably also try Vale.

[sirosen]

I'm interested in Vale, I think it looks very cool.

Less interested in using an LLM for this, personally. I'm waiting for the hype to die down, and plan to be a late adopter of the tech (after some not-great experiences trying it so far) assuming I can square it with my ethics.

[webknjaz]

I think it's important to have these files in the repo because people are going to use agentic help regardless of what we tell them. And if there's some guidelines, the chance of them producing rubbish would be decreased. With that, they wouldn't waste as much compute retrying or generating nonsense. So in my book helping such tools be efficient is definitely positive if we're talking about the environmental impact.

We just got such configuration in ansible/ansible#85841 just now and I'm interested in exploring making such configs for projects better.

[webknjaz]

@sirosen re:vale — I have this old issue where I collect various prose checkers @ aio-libs/multidict#276. If we succeed in integating any of them, I'd like to scale that to other projects.

[webknjaz]

I think it's important to have these files in the repo because people are going to use agentic help regardless of what we tell them. And if there's some guidelines, the chance of them producing rubbish would be decreased. With that, they wouldn't waste as much compute retrying or generating nonsense. So in my book helping such tools be efficient is definitely positive if we're talking about the environmental impact.

I opened a discussion for this @ #2278

[webknjaz]

Perhaps this should go into a separate pathlib_compat.py?

[sirosen]

My only concern would be that it might only ever have this one function.
What about a path_compat.py so that it's not only scoped to pathlib?

I wouldn't move other things over right away, but any helpers for handling drive letters and such could go there.

[sirosen]

I snooped around and immediately found a second helper to put in here!

I still prefer path_compat.py, so I'll go with that for the moment, but I'm happy to rename as well.

[sirosen]

I unfortunately ended up with a little bit of extra change needed ( 3df3efa ) because my desire to put two related helpers together created an import cycle. I can revert if this feels like too much extraneous change.

[webknjaz]

@sirosen circular imports is not a new problem. They've been annoying people trying to organize helpers for quite some time: #2108.

I think we should postpone moving other things into the new helper module as to keep the PR atomic and prevent scope creep growing infinitely.

[sirosen]

I think you're right, especially coming back to this after a couple of days.
I'm going to partially revert, cutting it back to just this one helper in a path_compat.py module, as part of my rebase right now.

[webknjaz]

The literal can also be linked.

Suggested change

	"""Return True if ``path1`` is relative to ``path2``."""
	"""Return :data:`True` if ``path1`` is relative to ``path2``."""

But as I said elsewhere, let's not include this helper.

[sirosen]

Since I reverted any move of this helper, I'm not changing the docstring, but 👍 to marking literals like this when possible.

[webknjaz]

Both 3.8 and 3.9 are both EOL already: https://endoflife.date/python. And testing against pip is becoming difficult in older runtimes.

I think we could plan dropping Python 3.8 once #2257 is implemented and released. With that, there would be no need to even think about hosting this function in compat modules.

[webknjaz]

Suggested change

	Compatibility helpers for working with paths and ``pathlib`` across platforms
	Compatibility helpers for working with paths and :mod:`pathlib` across platforms