Opened 2 years ago

Closed 2 years ago

#34224 closed New feature (wontfix)

App name in help text of commands is missing context

Reported by: David Owned by: nobody
Component: Core (Management commands) Version: 4.1
Severity: Normal Keywords:
Cc: Aymeric Augustin Triage Stage: Unreviewed
Has patch: no Needs documentation: no
Needs tests: no Patch needs improvement: no
Easy pickings: no UI/UX: no

Description

In the help text shown by python manage.py help, only the last part (after the last dot) of the app name is shown. See ManagementUtility.main_help_text.

Imagine a project that implements multiple apps; more than one of which defines custom commands:

  • project.core
  • project.app1
  • project.appN

These might show up as:

[appN]
    command_one
    command_two

[auth]
    ...

[contenttypes]
    ...

[core]
    command_one
    command_two

There are problems with this: It is not clear what "core", "appN" and so on, refer to, as they are missing the "project" context. And I don't think it is reasonable to assume that everybody who deploys this project will know by heart which of the apps belong to "project" and which don't. Due to the alphabetical sorting, apps belonging to the "project" are not grouped together which makes it more difficult to find relevant commands. In this example it would be nice to see this instead:

[django.contrib.auth]
    ...

[django.contrib.contenttypes]
    ...

[project.appN]
    command_one
    command_two

[project.core]
    command_one
    command_two

I think it would be beneficial to either allow the developer of an app to decide what is shown here, and/or show the full module/package name (by default). I'm sure both of these approaches also have drawbacks. I could imagine app names being quite long (even django.contrib.contenttypes is quite long already). Also people might try to "shadow" existing names.

Change History (1)

comment:1 by Mariusz Felisiak, 2 years ago

Cc: Aymeric Augustin added
Resolution: wontfix
Status: newclosed

Thanks for the ticket, however I have some doubts.

And I don't think it is reasonable to assume that everybody who deploys this project will know by heart which of the apps belong to "project" and which don't.

App names must by unique so there is no way to have two apps with the same name and you can always check a list of INSTALLED_APPS to figure out where an app comes from.

I think it would be beneficial to either allow the developer of an app to decide what is shown here, and/or show the full module/package name (by default).

You can override print_help() (or help_text) in your command to provide additional context when displaying help for a specific command, this should be enough to provide guidance to users. For example:

class Command(BaseCommand):
    ...
    def print_help(self, prog_name, subcommand):
        sys.stdout.write(f"Command provided by: {self.__class__.__module__}\n\n")
        super().print_help(prog_name, subcommand)

$ python manage.py help inspectdb

Command provided by: django.core.management.commands.inspectdb

usage: manage.py inspectdb [-h] [--database DATABASE] [--include-partitions] [--include-views] [--version] [-v {0,1,2,3}] 
...

If you don't agree, then please first start a discussion on the DevelopersMailingList, where you'll reach a wider audience and see what other think, and follow the guidelines with regards to requesting features.

Note: See TracTickets for help on using tickets.
Back to Top