Should management command verbosity levels be labelled?

Django Internals
1

The default verbosity levels of Django management commands are magic numbers; should those values be mapped to an object?

Context:

Django’s management commands provide each command with an optional verbosity argument with allowed values ranging from 0 to 3.

Each number represents a level which is described in the help function for commands, but not in the command class themselves: it is up to the developer to determine which output belongs to which level.

I personally found it more descriptive to map the values to sensibly named constants—or even better, an Enum—to remove some of the guesswork of what each level represents.

Code:

The manage. py help command provides this explanation for the available verbosity levels:

-v, --verbosity {0,1,2,3}
    Verbosity level; 0=minimal output, 1=normal output, 2=verbose output, 3=very verbose output

Which you could map to an enum like so:

from enum import IntEnum


class Verbosity(IntEnum):
    """Verbosity level corresponding to Django management command defaults."""

    MINIMAL_OUTPUT = 0
    NORMAL_OUTPUT = 1
    VERBOSE_OUTPUT = 2
    VERY_VERBOSE_OUTPUT = 3

What do you think?

NB. I expected there to already be a topic about this subject but could not find it. If this has already been discussed before, please feel free to share the relevant link.

3 Likes
2

<opinion>
As an addition or supplement to using the numbers, I guess I wouldn’t see an issue with that. (I can’t see me ever using them, but I acknowledge it can be considered a personal choice.)

I can’t see myself implementing them by name in the management commands that I create, nor would I envision myself implementing tests for them in my code, which means I’d be expecting Django to convert the names to numbers in the argument values passed to the handler.

As a replacement, I would be strongly against it, as it would create an uncommon convention for specifying levels.

In fact, if a change were to be made here, I’d prefer going in the other direction.

There are a number of linux commands that use repeated instances of -v, and/or patterns of -v, -vv, -vvv to identify the level of verbosity. (Some that I can think of right off-hand include tar, ssh, tcpdump, and pip.)

If any change were to be made, my preference would be to adhere more to the existing conventions rather that implementing something new.

Side note: POSIX doesn’t address this issue, merely to say that different levels of verbosity are program-specific - which also means that it’s valid to create a non-sequential set of verbosity levels. There’s nothing saying that the output of -vv or -v 2 must include the output of -v, although that does appear to be true for all examples I can think of.
</opinion>

3

I assumed the proposal only related to call_command() usage, not command-line usage, but that may have been a premature assumption!

1 Like
4

+1 for the simple fact that ruff complains about ‘magic’ numbers so in a custom management command having this available would be clearer in that code:
ie instead of

...
if verbosity >= 1:
...

having:

...
if verbosity >= Verbosity.NORMAL_OUTPUT:
...
2 Likes
5

+1 from me. I believe we will need an IntEnum to avoid breaking existing code. Let’s keep the names short: Verbosity.MINIMAL etc.

2 Likes
6

I assumed the proposal only related to call_command() usage, not command-line usage, but that may have been a premature assumption!

This assumption is correct; my recommendation is for Python code only.

I like Ken’s proposal as well, but that would be a separate discussion and lead to a possibly breaking change for existing management command calls.

7

Like so then?

from enum import IntEnum


class Verbosity(IntEnum):
    MINIMAL = 0
    NORMAL = 1
    VERBOSE = 2
    VERY_VERBOSE = 3
2 Likes
8

I created a GitHub ticket based off this idea:

2 Likes