Always list all positional arguments

[kdeldycke]

This is inconsistent with the way options are displayed, as every options are displayed including those without help.

The reason to display all arguments in the Positional arguments section is to not introduce subtle confusion, as an argument without help would only be noticeable in the usage line.

Cloup already renders the section this way (see janluke/cloup#210) and is the source discussion with @janluke for that bug fix.

In this implementation, I refrained to always display the Positional arguments section. So I made the decision to not print the Positional arguments section in full if and only if at least one of its argument has an help. This decision is open to discussion.

This is a follow up on #3473

[janluke]

Of course, I approve the change in behavior, since that's what I decided for Cloup as well.

The code looks correct, but I think we should consider changing get_help_record to always return a tuple (never None; unless this turns useful elsewhere):

    def get_help_record(self, ctx: Context) -> tuple[str, str]:
        return self.make_metavar(ctx), self.help or ""

Returning None when help is None is only hurting us now.

Also, this might read a bit more Pythonic:

    def format_arguments(self, ctx: Context, formatter: HelpFormatter) -> 
        args = [
            param
            for param in self.get_params(ctx)
            if isinstance(param, Argument)
        ]
        if any(arg.help for arg in args):
            # assuming arg.get_help_record() always returns a help re
            help_records = [arg.get_help_record(ctx) for arg in args]
            ...

[kdeldycke]

Of course, I approve the change in behavior, since that's what I decided for Cloup as well.

The code looks correct, but I think we should consider changing get_help_record to always return a tuple (never None; unless this turns useful elsewhere):

    def get_help_record(self, ctx: Context) -> tuple[str, str]:
        return self.make_metavar(ctx), self.help or ""

Returning None when help is None is only hurting us now.

The reason for keeping get_help_record returning tuple[str, str] | None is to keep the Parameter, Option and Argument classes aligned.

I propose to evaluate this change in another PR as this opened a related issue I just stumbled upon. I will open a new one today and ping you there for feedback. Let's keep this PR focused on Positional arguments behavior for now.

Also, this might read a bit more Pythonic:

    def format_arguments(self, ctx: Context, formatter: HelpFormatter) -> 
        args = [
            param
            for param in self.get_params(ctx)
            if isinstance(param, Argument)
        ]
        if any(arg.help for arg in args):
            # assuming arg.get_help_record() always returns a help re
            help_records = [arg.get_help_record(ctx) for arg in args]
            ...

Good point. Just applied your changes.

[kdeldycke]

Returning None when help is None is only hurting us now.

The reason for keeping get_help_record returning tuple[str, str] | None is to keep the Parameter, Option and Argument classes aligned.

I propose to evaluate this change in another PR as this opened a related issue I just stumbled upon. I will open a new one today and ping you there for feedback. Let's keep this PR focused on Positional arguments behavior for now.

OK I get it now. You are right, this change should be bundled in this PR, as it highlight the policy of refusing to allow an argument to be hidden. Just made the changes.

This PR is ready to be reviewed.