Clarify set-valued marker handling for extras and selected-extra evaluation

[KRRT7]

Summary

While working on pypa/pip#14139, pip needed to evaluate metadata extra markers against the full set of extras selected for a requirement.

packaging.markers.Marker.evaluate() evaluates extra as a single string in one marker environment, which makes sense for the current API. For installers, though, the useful semantics are set-wide:

• extra == "gpu" should match if gpu is one of the selected extras.
• extra != "gpu" should match only if gpu is not selected.
• extra not in ... needs similar set-wide negation semantics.

Without a public helper for that, pip currently needs custom marker-walking logic or repeated single-extra evaluation with special handling for negated comparisons.

While looking at this, I also noticed that the newer set-valued extras marker variable works in some expression shapes, but raises an internal AssertionError in others.

Reproducer

import packaging
from packaging.markers import Marker

print("packaging", packaging.__version__)

env = {"extras": frozenset({"gpu"})}

for expr in [
    '"gpu" in extras',
    '"cpu" not in extras',
    '"gpu" not in extras',
    'extras == "gpu"',
    'extras != "gpu"',
    'extras in "gpu,docs"',
    'extras not in "gpu"',
]:
    marker = Marker(expr)
    try:
        result = marker.evaluate(env, context="lock_file")
    except Exception as exc:
        result = f"{type(exc).__name__}: {exc}"
    print(f"{expr} -> {result}")

Observed behavior

With packaging 26.2:

packaging 26.2
"gpu" in extras -> True
"cpu" not in extras -> True
"gpu" not in extras -> False
extras == "gpu" -> AssertionError: lhs must be a string
extras != "gpu" -> AssertionError: lhs must be a string
extras in "gpu,docs" -> AssertionError: lhs must be a string
extras not in "gpu" -> AssertionError: lhs must be a string

Questions

Is the intended API that set-valued marker variables such as extras only work when the set-valued variable appears on the RHS of in / not in, for example:

Marker('"gpu" in extras')

If so, should unsupported expression shapes such as extras == "gpu" raise a public exception instead of an internal AssertionError?

Separately, would packaging be open to exposing a public helper for evaluating metadata extra markers against a selected extras set?

For pip's use case, metadata still uses extra, not extras, so the useful API would be something like "evaluate this marker against these selected extras using installer semantics". That would let tools avoid depending on Marker._markers internals or reimplementing part of marker evaluation.

Context:

• pip issue: extra != '...' environment markers always evaluate to true pip#14139
• pip PR exploring the installer-side fix: Fix extra marker evaluation for requested extras pip#14141

[geofft]

See also https://discuss.python.org/t/the-extra-environment-marker-and-its-operators/4976 for a little bit of context, including at the very bottom a proposal that there should be an Extra class that represents a set of extras and has an __eq__ operator that implements set-membership.

Regarding extra vs. extras, please note the language in the spec about the extras field, the three paragraphs right after the table.

[brettcannon]

The only potential issue I can see being raised here is the AssertionError instead of a TypeError. Otherwise I don't see how any of this doesn't follow the spec at https://packaging.python.org/en/latest/specifications/dependency-specifiers/ . And as Geoff pointed out, there's already a discussion going on about operators.

[henryiii]

AssertionError was fixed three days later by #1265 (now UndefinedComparison).

I have an ExtraSet class in a branch extra-set in my fork that allows evaluate(environment={"extra": {"one", "two"}}), I think that could be useful. It's based on extra at the moment, I have to look up extras, I've not followed that closely, until then I'm avoiding PR'ing anything.

Currently we are not following the spec recommendation of False for other operators on extra, like <=, we should probably fix that.

I'd be tempted to not touch anything quite yet until the negative extra discussion (pypa/packaging.python.org#2085) settles.