Extend dependency specifier syntax to allow specifying multiple allowed version intervals for the same package

[codethief]

Summary

Some packages like protobuf maintain several major versions at the same time. So when my project uses protobuf and needs to constrain its version (e.g. because a certain bug fix is only available in the version intervals >=3.27,<4, >=4.30,<5, >=5.27,<6, >=6.30,<7), it would be great if this could be done for each major version separately, so that downstream projects can still choose the major version of protobuf somewhat freely. It should also be possible to combine this with the python_version constraint. In other words, I want to be able to specify something like:

If python_version >= 3.14, use protobuf version >=3.27,<4 OR >=4.30,<5 OR >=5.27,<6 OR >=6.30,<7.

Real-life inspiration: pulumi/pulumi#21828 (comment)

Example

I'm not entirely sure about the syntax yet and am likely not fully aware of all constraints (pun intended). What I'm suggesting basically amounts to introducing a logical OR operator to combine multiple version specifiers in a single dependency specifier. Here is one suggestion for the syntax, using or as logical delimiter:

[project]
dependencies = [
  'protobuf>=3.20.3,<7; python_version < "3.14"',
  'protobuf>=3.27,<4 or >=4.30,<5 or >=5.27,<6 or >=6.30,<7; python_version >= "3.14"',
]

(and similarly for other places where package versions are specified, e.g. project.optional-dependencies, development dependencies / dependency groups, tool.uv.constraint-dependencies, tool.uv.override-dependencies etc.)

Notes regarding the different delimiters:

• According to the version specifier spec, the comma , in something like protobuf>=3.27,<4 should be interpreted as logical AND.
• The semicolon ; in a dependency specifier like protobuf>=3.27,<4; python_version >= "3.14" might also seem to act as a logical AND. However, python_version is actually a special environment marker and probably closer in spirit to an if.
• and and or can already be used to combine environment markers, so the above suggestion to use or would be consistent with that.

EDIT: Originally, I was mostly thinking about allowing logical ORs in tool.uv.constraint-dependencies and tool.uv.override-dependencies, the syntax of which uv could probably extend quite easily. For project.dependencies and project.optional-dependencies, however, I realize one would probably need to augment the pyproject.toml specification for compatibility across package managers. So maybe this is the wrong forum to discuss this. (OTOH given how popular uv is, the uv devs could probably steer such a discussion more easily than others.) Either way, I'm leaving the ticket open if only to document for others that specifying multiple version intervals is currently not supported – something which took me quite a bit of time to find out.

[woodruffw]

Hi @codethief, thanks for opening an issue.

I think the conclusion at the bottom of your post is correct: version spans/specifiers are defined in the Version Specifiers Specification, so support for disjunction would need to go through the Python packaging standards process.

Off the top of my head, the simplest workaround for this is probably to use optional dependencies, i.e. extras. However, it's not particularly nice or ergonomic and I wouldn't actually recommend it:

[project.optional-dependencies]
protobufv3 = ["protobuf>=3.27,<4"]
protobufv4 = ["protobuf>=4.30,<5"]
# etc.

Then, a user would do uv add your-pkg[protobufv3] or similar to select the appropriate extra. This comes with significant downsides, however: Python packaging doesn't have default extras, so anybody who does uv add your-pkg will get a broken package instead (or worse, one that silently works because some version of protobuf happens to already be installed).

However, to take a step back: what's the underlying reason you need to encode those disjunctions, rather than a single protobuf>=3.27,<7 constraint?

[codethief]

Thank you for responding so quickly!

However, to take a step back: what's the underlying reason you need to encode those disjunctions, rather than a single protobuf>=3.27,<7 constraint?

If a bug is present in, say, protobuf v3.26, v4.29, v5.26, and v6.29, and my project relies on this bug being fixed, then it requires a protobuf version ∈ [3.27, 4) ∪ [4.30, 5) ∪ [5.27, 6) ∪ [6.30, 7). Otherwise, if I specified protobuf>=3.27,<7, then it would be perfectly valid for downstream projects to install protobuf 4.11, say, but then the bug would surface.

For a real-world example, again see pulumi/pulumi#21828 (comment) . For the record, I don't work on Pulumi, though. I just thought I'd take the opportunity to raise this matter, since I use Pulumi as a dependency in my project and this is not the first time I'm running into this situation with one of my dependencies. The Python 3.14 update in particular has been causing a lot of bugs/errors to appear in my project's (transitive) dependencies.