Fix eagerness of help option generated by help_option_names

[kdeldycke]

When a help option is generated by the use of help_option_names setting, it loose its eagerness. This issue has an effect on the order in which parameters (and their callbacks) are processed, and breaks the evaluation order described in the documentation: https://click.palletsprojects.com/en/stable/advanced/#callback-evaluation-order

That's because the utility method iter_params_for_processing() is comparing option objects, and the help option is generated on every get_help_option() or get_params(ctx) call. This behavior is demonstrated by a unit-test in this PR.

My solution to fix this issue consist in caching locally the auto-generated help option. This solves the issue.

I used this oportunity to clarify some documentation, and unit-test the main method responsible for the ordering of parameters.

This is more or less a follow up of #2563, which has been merged in the upcoming v8.1.8 release.

Checklist:

• Add tests that demonstrate the correct behavior of the change. Tests should fail without the change.
• Add or update relevant docs, in the docs folder and in code.
• Add an entry in CHANGES.rst summarizing the change and linking to the issue.
• Add .. versionchanged:: entries in any relevant code docs.
• Run pre-commit hooks and fix any issues.
• Run pytest and tox, no tests failed.

[kdeldycke]

Just fixed all the remaining issues.

I was just wondering why get_help_option() couldn't be replaced by a @cached_property like that:

    @cached_property
    def help_option(self) -> t.Optional["Option"]:
        ctx = self.get_current_context()
        help_options = self.get_help_option_names(ctx)

        if not help_options or not self.add_help_option:
            return None

        # Avoid circular import.
        from .decorators import HelpOption
        
        return HelpOption(help_options)

    def get_help_option(self, ctx: Context) -> t.Optional["Option"]:
        return self.help_option

But I guess there are some edge-cases regarding the context management. And I don't want to propose refactors that are too deep just as 8.1.8 is around the corner and the 8.2.0 is coming soon after.

Anyway, this PR is ready to be merged upstream for the 8.1.8 release.

[AndreasBackx]

Thanks for the fix!

We can look at cached properties in the future perhaps. I'm not bothered by a simple if None.

[kdeldycke]

Thanks @AndreasBackx for the merge!