Customizable management command formatters.

[James Pic]

With code like:

class Command(BaseCommand):
    help = '''
    Import a contract from tzkt.

    Example usage:

        ./manage.py tzkt_import 'Tezos Mainnet' KT1HTDtMBRCKoNHjfWEEvXneGQpCfPAt6BRe
    '''

Help output is:

$ ./manage.py help tzkt_import
usage: manage.py tzkt_import [-h] [--api API] [--version] [-v {0,1,2,3}] [--settings SETTINGS]
                             [--pythonpath PYTHONPATH] [--traceback] [--no-color] [--force-color]
                             [--skip-checks]
                             blockchain target

Import a contract from tzkt Example usage: ./manage.py tzkt_import 'Tezos Mainnet'
KT1HTDtMBRCKoNHjfWEEvXneGQpCfPAt6BRe

positional arguments:
  blockchain            Name of the blockchain to import into
  target                Id of the contract to import

When that was expected:

$ ./manage.py help tzkt_import
usage: manage.py tzkt_import [-h] [--api API] [--version] [-v {0,1,2,3}] [--settings SETTINGS]
                             [--pythonpath PYTHONPATH] [--traceback] [--no-color] [--force-color]
                             [--skip-checks]
                             blockchain target

Import a contract from tzkt 

Example usage: 

    ./manage.py tzkt_import 'Tezos Mainnet' KT1HTDtMBRCKoNHjfWEEvXneGQpCfPAt6BRe


positional arguments:
  blockchain            Name of the blockchain to import into
  target                Id of the contract to import

[Tim Graham]

This seems no fault of Django but is rather ​the default behavior of ArgumentParser ("By default, ArgumentParser objects line-wrap the description and epilog texts in command-line help messages"). This can be changed by using a custom ​formatter_class, though Django already specifies a custom one (​DjangoHelpFormatter).

[Mariusz Felisiak]

It seems reasonable, to make it customizable by passing via kwargs to the ​BaseCommand.create_parser() (as documented):

django/core/management/base.py

@@ -286 +286 @@
         Create and return the ``ArgumentParser`` which will be used to
         parse the arguments to this command.
         """
+        kwargs.setdefault("formatter_class", DjangoHelpFormatter)
         parser = CommandParser(
             prog="%s %s" % (os.path.basename(prog_name), subcommand),
             description=self.help or None,
-            formatter_class=DjangoHelpFormatter,
             missing_args_message=getattr(self, "missing_args_message", None),
             called_from_command_line=getattr(self, "_called_from_command_line", None),
             **kwargs,

What do you think?

[James Pic]

Looks good but I don't see a reason for keeping a default that swallows newlines because PEP257 forbids having a multiline sentence on the first line anyway:

Multi-line docstrings consist of a summary line just like a one-line docstring, followed by a blank line, followed by a more elaborate description.

As such, the default formater which purpose is to unwrap the first sentence encourages breaking PEP 257.

And users who are naturally complying with PEP257 will have to override the formatter, it should be the other way around.

[James Pic]

Also, the not-unwraping formater will also look fine with existing docstrings, it will work for both use cases, while the current one only works for one use case and breaks the other. The default formater should work for both

[Mariusz Felisiak]

Replying to James Pic:

Also, the not-unwraping formater will also look fine with existing docstrings, it will work for both use cases, while the current one only works for one use case and breaks the other. The default formater should work for both

It seems you think that Python's (not Django's) default behavior should be changed according to PEP 257. I'd recommend to start a discussion in Python's bugtracker. As far as I'm aware the proposed solution will allow users to freely change a formatter, which should be enough from the Django point of view.

[James Pic]

No, I think that Django's default behavior should match Python's PEP 257, and also, have a default that works in all use cases.

Unless you have any specific question about this statement, I'm going to give up on this.

[Subhankar Hotta]

So as part of this issue, do we make changes to allow a user to override the formatter through kwargs and also keep DjangoHelpFormatter as the default?

[Mariusz Felisiak]

Replying to Subhankar Hotta:

So as part of this issue, do we make changes to allow a user to override the formatter through kwargs and also keep DjangoHelpFormatter as the default?

Yes, see comment.

[Abhinav Yadav]

​PR

[GitHub <noreply@…>]

In 2887b9f:

Fixed #33657 -- Allowed customizing formatter class of argument parsers.

[Mariusz Felisiak <felisiak.mariusz@…>]

In 99e5ce96:

[4.1.x] Fixed #33657 -- Allowed customizing formatter class of argument parsers.

Backport of 2887b9f67cadc5295ef6a0574de2c2c8fdd66905 from main