📦 Add a stable extra for pip upper bound

[webknjaz]

It is supposed to correspond to the range of what's tested in our CI.

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]

We'll need some sort of linting for keeping these in sync w/ CI and perhaps docs.

[Copilot]

Pull Request Overview

This PR introduces version constraints for pip to ensure compatibility testing. It adds a new optional dependency group called supported-pip that limits pip to versions below 25.3, and integrates this constraint into the tox testing environments for pipsupported and piplowest configurations.

• Added a new supported-pip optional dependency group in pyproject.toml with pip version constraint < 25.3
• Updated tox configuration to use the supported-pip extras for pipsupported and piplowest test environments

Reviewed Changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated no comments.

File	Description
pyproject.toml	Adds supported-pip optional dependency group with pip version constraint
tox.ini	Integrates supported-pip extras into pipsupported and piplowest test environments

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[sirosen]

I am trying to decide what we should name this extra -- not taking it as a given that the proposed name, supported-pip, is best.

I think supported-pip may be confusing if we start pinning anything other than pip in the future. And I think we should at least start with pip-only, which makes the possibility of such confusion stronger in the future. So I think we should remove pip from the name of the extra.

That would leave us with pip-tools[supported], which I think is good. I can't come up with anything better, at least!

[webknjaz]

I think supported-pip may be confusing if we start pinning anything other than pip in the future. And I think we should at least start with pip-only, which makes the possibility of such confusion stronger in the future. So I think we should remove pip from the name of the extra.

That would leave us with pip-tools[supported], which I think is good. I can't come up with anything better, at least!

That's a good point. Alternatively, we could have multiple composable extras and the users could use pip-tools [supported-click, supported-pip].

[webknjaz]

@sirosen should we include this in 7.5.2?

[sirosen]

I still feel uncertain about it, at least as far as naming is concerned.
I'm going to put it into the 7.5.3 milestone so that we're not feeling pressured at all to rush discussion here.

[webknjaz]

Okay, fair.

[sirosen]

I have been thinking about the name here even more. The supported name is still "wrong" for me in a way that I'm having trouble ignoring, even though I want us to add this extra.

My main issue is that the opposite of "supported" is "unsupported", so I don't like the possible implication that pip install 'pip-tools[supported]' means "you are supported" and pip install 'pip-tools' means "you are unsupported".
We would obviously not behave that way, but it may be how users read it.

What if we used stable instead?
We could have this suite of extras:

stable-pip: pip <= {tested-version}
stable-click: click <= {tested-version}
stable: pip-tools[stable-pip], pip-tools[stable-click]

(We could start with stable alone, and refactor to this if we feel the need to provide more control.)

Stable/unstable is common terminology, and for Python users, familiar with RTD sites, stable/latest is also common.
Both of those seem to properly communicate "there's a chance that this could break which we can't fully control".

@webknjaz, WDYT? pip-tools[stable]? And the more I think about it, the more I'm okay with it capping the click version.

[webknjaz]

stable sounds good. Could also be tested / confirmed-working.

[webknjaz]

@sirosen I've made all the requested changes but I'm not sure if it's time to undraft this yet. Perhaps, we should have some linting/automation for keeping things in sync as a prerequisite for merging the patch.

[webknjaz]

📚 https://pip-tools--2257.org.readthedocs.build/en/2257/changelog/#unreleased-changes

[wyattscarpenter]

I'm quite looking forward to this extra as I've been requiring pip-tools as a dev dependency and have been stymied lately by #2252 and a previous pip–pip-tools compatibility problem along the same lines. So it will be quite useful to me to be able to require this extra at some point, to easily give users a known-good configuration. (Although I may cease maintaining my project before this PR lands.)

With that in mind, I +0.5 the idea that this PR should be undrafted and incorporated as soon as possible, and the linting/automation to keep it in sync (which is also important) should be a subsequent PR. I mean, the stable requirement is hardly going to get less stable fast if it isn't updated, right? I'd like to be able to require [stable] as soon as the next release of pip-tools, if possible, which will give me compatibility now and effortless forwards-compatibility later; likely a strict improvement on the current situation where I pin on my end.

There also doesn't seem to be anywhere where the current compatibility with pip is listed in the docs, although I may have missed something. There used to be one with #1089 but that seems gone now. This is a mixed blessing because it means I, personally, currently have nowhere to look for that, but also that's one fewer thing to ensure compatibility with using the aforementioned "automation for keeping things in sync".

This extra should probably be mentioned in the readme/documentation, and not just the changelog. Its name is not fully self-explanatory (and can't be; its name would have to be a complicated sentence in its own right to be fully explanatory) yet it is a feature that will be useful to end-users.

It seems to me like you should just require known-good dependencies by default and then rely on the user to pass --no-dependencies if they want to override that? But I'm no python packaging guru; I'm sure you have reasons for doing it the opt-in way.

[webknjaz]

With that in mind, I +0.5 the idea that this PR should be undrafted and incorporated as soon as possible, and the linting/automation to keep it in sync (which is also important) should be a subsequent PR. I mean, the stable requirement is hardly going to get less stable fast if it isn't updated, right? I'd like to be able to require [stable] as soon as the next release of pip-tools, if possible, which will give me compatibility now and effortless forwards-compatibility later; likely a strict improvement on the current situation where I pin on my end.

I'm a bit uncertain, because this increases the risk of having multiple places out-of-sync. But if @sirosen @beruic have different opinions, we could probably make such a split.

@wyattscarpenter FTR, you could technically start depending on this extra already — Python ecosystem usually ignores those that don't exist.

There also doesn't seem to be anywhere where the current compatibility with pip is listed in the docs, although I may have missed something. There used to be one with #1089 but that seems gone now. This is a mixed blessing because it means I, personally, currently have nowhere to look for that, but also that's one fewer thing to ensure compatibility with using the aforementioned "automation for keeping things in sync".

Yeah, people wanted to get rid of the manually maintained table some time ago. I don't recall being too happy about it but I was also less involved, I suppose. Somebody from GH removed it: #1950.

It's been on my mind for quite a while too: #2148 (comment).

Actually, @sirosen and I also had the exact same conversation in the fall about needing to ressurect that. And I want this to be provided by a Sphinx extension instead of being hardcoded in README.

This extra should probably be mentioned in the readme/documentation, and not just the changelog. Its name is not fully self-explanatory (and can't be; its name would have to be a complicated sentence in its own right to be fully explanatory) yet it is a feature that will be useful to end-users.

Agreed.

It seems to me like you should just require known-good dependencies by default and then rely on the user to pass --no-dependencies if they want to override that? But I'm no python packaging guru; I'm sure you have reasons for doing it the opt-in way.

There's been a lot of interest in this over many years but we still don't have a metadata standard to express this. And so I don't think that any installer will support such feature until there's an accepted PEP.
If you're interested, there's PEP 771 which is a draft: https://discuss.python.org/t/pre-publish-pep-771-default-extras-for-python-software-packages/77892 / https://wheelnext.dev/proposals/pep771_default_extras/ / https://peps.python.org/pep-0771/ /

[sirosen]

Yeah, I think we have to figure out what we want a little, which is why I've been avoiding putting any pressure on this PR to move faster.

Actually, @sirosen and I also had the exact same conversation in the fall about needing to ressurect that. And I want this to be provided by a Sphinx extension instead of being hardcoded in README.

I'm still not totally sure what I think we should do about older versions of pip-tools, which is to say "not the latest". But we definitely can keep a documented statement of "pip-tools is tested against pip versions 19.2 through 27.1" (obviously fake numbers 😉 ).

For the current version, it's easier to decide to document it, but for older versions... we enter more murky territory, since we don't actively support old versions. I'd have trouble picking out how many we document.

---

I'm considering the merits of using the pip-tools[stable] extra as the source of truth for this information. If we have pip-tools[stable], I think it should be possible to wire up

• a script which extracts the pip version bounds from project metadata (lower from project.dependencies, upper for project.optional-dependencies.stable)
• templating with cog or similar (I've been using it a lot lately and enjoying it) to inject those bounds into tox.ini and docs
• a CI job to check for drift

I think that's sufficiently separate from the goal of this PR that I wouldn't want to fold it in.

@webknjaz, what do you think of opening an issue for using pip-tools[stable] as the canonical source of truth, and unblocking this? I strongly agree that we want to keep things in sync, and we'd like that to be automated, but we have the ability to do it manually today.

[webknjaz]

I wouldn't care about the older versions until somebody asks. That's busy work that we don't have a proof anybody will ever want to make use of. I also like Sphinx over cog because this allows not having extra commits to display stuff.

An issue sounds good.

[webknjaz]

I didn't get into detail in my previous response b/c I had a health incident and wasn't feeling well. Here's a few more notes I had in mind.

---

I'm considering the merits of using the pip-tools[stable] extra as the source of truth for this information

Either this, or the oposite direction would be an in-tree PEP 517 build backend wrapper. Having a standard backend is probably less maintenance overhead. And PEP 621 is good as the source of truth.

• to inject those bounds into tox.ini and docs

Both have plugin systems in place. It's quite easy to use toxfile.py and docs/conf.py to inject centrally sourced info both runtimes. We'd probably make use of a shared utility module for parsing it.

For tox, this would be the tox_add_env_config() hook.
And for Sphinx, it'd be an RST directive — it's pretty easy to generate an RST table and feed it to the helpers, having it injected into the document (I've got some examples of prior art in sphinxcontrib-towncrier and old versions of ansible-lint or ansible-navigator, I think).

• a CI job to check for drift

Ideally, the CI matrix would be generated from the same info w/o any need to have additional checks. OTOH, with the current mapping to tox factors with min/max pip, this isn't even needed in the current form.