Rename UnionParamType to FirstOf, change implementation to take positional args, fully typehint, more verbose errors, optional return tuple with param used for conversion.

[laundmo]

This PR does a few things with the UnionParamType which i accidentally re-implemented in a project of mine. I fully understand if the changes to the API/usage are not wanted, though personally i find they increase readability a lot.

• Renames it to FirstOf which is more in line with click names like Choice
• Changes argument to *param_types, which looks cleaner in user code: FirstOf(click.INT, click.FLOAT)
• In case no name is given, use a python set union as a name: (a | b)
• Fully typehints it (passes mypy and strict pyright), only issue is the Any return on convert which isn't resolvable without major changes to click and click_params
• Makes errors more verbose by passing out the individual errors of the ParamTypes passed in. This also works with nested FirstOf
• Optionally return the ParamType instance/type used for the conversion, for use cases where the conversion used determines some functionality of the command.

Example error of a nested FirstOf (no names given, therefore default union name used):

Error: Invalid value for '-j': All possible options exhausted without any successful conversion:
 -  (INTEGER | (INTEGER | FLOAT)): All possible options exhausted without any successful conversion:
  -  INTEGER: 'asdas' is not a valid integer.
  -  (INTEGER | FLOAT): All possible options exhausted without any successful conversion:
   -  INTEGER: 'asdas' is not a valid integer.
   -  FLOAT: 'asdas' is not a valid float.
 -  INTEGER: 'asdas' is not a valid integer.

Checklist:

• [x] Changed functionality
• [x] Updated tests which pass.
• [x] Updated relevant docs.

[lewoudar]

Hi @laundmo thank you for this well-defined pull request Honestly I don't have arguments and feedback against the changes to this parameter, so it is OK for me But the tests are not passing, can you fix them please?

[laundmo]

Of course, I'll try. They were passing locally though which makes this quite odd.

[lewoudar]

Thanks a lot for this PR @laundmo I have to refine a bit the code, but I will try to release a new version by the end of the week

[laundmo]

Just noticed i forgot to add to changelog, might be something you want to have a look at.

[lewoudar]

Yeah I thought about it :)