"default" behaviour in Click 8.3.x changes with enable/disable boolean flag pair

[freakboy3742]

In click 8.2.1, defining a boolean option with both a "enable" and "disable" flag option works with the following logic:

import click

@click.command("foo")
@click.option("--without-xyz", "enable_xyz", flag_value=False)
@click.option("--with-xyz", "enable_xyz", flag_value=True, default=True)
def foo(enable_xyz):
    print(f"enable_xyz = {enable_xyz}")

foo()

With this code, using click 8.2.1:

• python foo.py --with-xyz returns True
• python foo.py --without-xyz returns False
• python foo.py --with-xyz --without-xyz returns False
• python foo.py --without-xyz --with-xyz returns True
• python foo.py returns False

In click 8.3.0, the output is the same for every case except the "default" case - python foo.py returns True.

This is an extension of #3111; this pattern is used in MkDocs (as of MkDocs 1.6.1) (see mkdocs/mkdocs#4032).

However, the fix for #3111 (#3239) doesn't fix this edge case.

The Properdocs fork of MkDocs has worked around the issue.

Environment:

• Python version: 3.12, 3.13, 3.14
• Click version: 8.3.0, 8.3.3

[Rowlando13]

Your example is working correctly in 8.3.3. In 8.2.x there were a lot of flag bugs because we would fix something and break something else because of how tangled up the internals were.

[Rowlando13]

The 'default=true' means this is the default option. See improved flag docs

[freakboy3742]

Your example is working correctly in 8.3.3.

So - are you saying that the behaviour of the script that I've provided is "operating as intended" under 8.3.3, despite the backwards incompatibility in the behavior observed with 8.2.x?

(Not necessarily disagreeing with the interpretation - just trying to work out if this is an intentional backwards incompatibility that needs to be accommodated, and this issue can/should be closed; or if this ticket should be left open as it could be addressed at some point).

[davidism]

Short answer: I think yes, the change was intended. @kdeldycke will have to take a look too, he's the one who's been working on all this.

The problem is that this was all pretty ambiguous, and none of it seemed designed particularly intentionally. So we're trying to untangle a lot of interacting behaviors and hard to maintain code behind the scenes. The behavior we settled on with "default=True" indicating the default of many overlapping options seems to make sense and be consistent.

I do see that it changed the default behavior in the example. But 8.2 to 8.3 was a feature release, so it could break compatibility according to our long standing version policy. Obviously not ideal, but I don't know if it would have been possible to deprecate first, or to stick with the previous behavior and still achieve our refactoring and consistency goal.

Note also in that version policy that only the latest version is supported. So mkdocs would be completely fine (and help the ecosystem along) if they updated to >= 8.3.3 and swapped where the default=True was applied.

[kdeldycke]

With this code, using click 8.2.1:

• python foo.py --with-xyz returns True
• python foo.py --without-xyz returns False
• python foo.py --with-xyz --without-xyz returns False
• python foo.py --without-xyz --with-xyz returns True
• python foo.py returns False

Nice matrix of cases. The issue lies in options competing for the enable_xyz item, and the first write wins. In 8.2.x, the last write wins.

I will experiment in a WIP PR and try to retrace the change history.

[kdeldycke]

I think it has less to do with the defaults being set to True than the nature of the dual flags sharing the same enable_xyz option name. That part of Click has been fragile and uncovered by tests until 8.3.0. See: c498ced

But it could also be a composed sub-case of dual flags that only happens for boolean flags. Anyway. WIP at #3404