`ParamType.get_metavar` has a new mandatory argument in 8.2.0

[peterdragun]

I am using the get_metavar function to generate a custom metavar for some types. This was working fine, but upgrading Click to 8.2.0 broke our script. Unlike some other functions (e.g., get_missing_message), this is not even mentioned in the documentation that such a parameter was introduced. See (docs link):

Overall, such changes to the public documented API should not add mandatory parameters because that is adding breaking changes into a minor release. I get that this was added to enable a new feature, but I think you should consider using it as an optional parameter, which still adds a benefit of a new feature, while not introducing breaking changes to the public API.

Steps to reproduce:

1. Use click 8.1.x
2. Call get_metavar to get some custom metavar (get_metavar has one parameter - param)
3. Update to 8.2.0
4. CLI crashes because a new mandatory parameter was introduced

Expected behavior:

No breaking changes to the public API in minor release, and better document the new parameter as you do for other functions.

Environment:

• Python version: 3.13
• Click version: 8.2.0

[davidism]

No breaking changes to the public API in minor release, and better document the new parameter as you do for other functions.

8.2 is a feature release. Please see our version support policy for an explanation of our version numbers.

We'll add this to the release notes.

[robfraz]

I'm also hit similar issues for this with make_metavar in the Parameter class.

TypeError: Parameter.make_metavar() missing 1 required positional argument: 'ctx'

In 8.1.8: https://github.com/pallets/click/blob/8.1.8/src/click/core.py#L2218
In 8.2.0: https://github.com/pallets/click/blob/8.2.0/src/click/core.py#L2208

[peterdragun]

Hi @davidism, thanks for the quick response. As the linked document says - "We do our best to avoid breaking documented APIs without first showing deprecation warnings..." - I still believe that such changes could be done by introducing an optional parameter with default to None, so that people can benefit from this new feature, but the old API is not changed.

For this case, I believe that adding a release note and an update to the documentation about this new parameter is reasonable unless you would like to change this to an optional parameter with the next patch release.

[codesorcery]

Note that this currently also breaks compatibility with some parts of the typer library.
E.g. the usage of make_metavar at https://github.com/fastapi/typer/blob/38d1873c80571fb07b5597a7a443086085bdbc27/typer/rich_utils.py#L373

[davidism]

If all you're doing is calling the method, then yes optional with a deprecation warning will fix compat. But presumably you're overriding the method to change its behavior? In that case making the argument optional won't fix compat, because it's the code that overrides the method that needs to change its signature to match. (It's possible with complex/slow introspection to handle old signatures, but that's not a tradeoff we can make in a CLI application.)

[nathan-chappell]

Note that this currently also breaks compatibility with some parts of the typer library. E.g. the usage of make_metavar at https://github.com/fastapi/typer/blob/38d1873c80571fb07b5597a7a443086085bdbc27/typer/rich_utils.py#L373

29 minutes ago? I was here to say the same thing. Ironically, I ran into this while refactoring my own code to avoid this exact issue...

Basically just another complaint about this breaking typer...

[dimaqq]

Specifically, projects that use typer fail.

Example:

• uvx --with=click==8.1.8 juju-doctor --help ✅
• uvx --with=click==8.2.0 juju-doctor --help ❌

[davidism]

Locking to prevent further "me too" comments. Maintainers will discuss how to handle this.