[Django] #34224: App name in help text of commands is missing context

4 views

Skip to first unread message

Django

unread,

Dec 22, 2022, 5:30:31 AM12/22/22

to django-...@googlegroups.com

#34224: App name in help text of commands is missing context
-------------------------------------+-------------------------------------
Reporter: David | Owner: nobody
Type: New | Status: new
feature |
Component: Core | Version: 4.1
(Management commands) |
Severity: Normal | Keywords:
Triage Stage: | Has patch: 0
Unreviewed |
Needs documentation: 0 | Needs tests: 0
Patch needs improvement: 0 | Easy pickings: 0
UI/UX: 0 |
-------------------------------------+-------------------------------------
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.

--
Ticket URL: <https://code.djangoproject.com/ticket/34224>
Django <https://code.djangoproject.com/>
The Web framework for perfectionists with deadlines.

Django

unread,

Dec 23, 2022, 6:27:24 AM12/23/22

to django-...@googlegroups.com

#34224: App name in help text of commands is missing context
-------------------------------------+-------------------------------------
Reporter: David | Owner: nobody

Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
-------------------------------------+-------------------------------------

Changes (by Mariusz Felisiak):

* cc: Aymeric Augustin (added)
* status: new => closed
* resolution: => wontfix

Comment:

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:

{{{#!python
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
[https://docs.djangoproject.com/en/stable/internals/contributing/bugs-and-
features/#requesting-features follow the guidelines with regards to
requesting features].