Argparse: Cryptic usage message when combining `choices` with `type`

[hansthen]

Bug report

Bug description:

Combining argparse type and choices arguments results in cryptic usage messages.

import argparse

parser = argparse.ArgumentParser()

day_names = ["mo", "tu", "we", "th", "fr", "sa", "su"]
days = [1, 2, 3, 4, 5, 6, 7]

def name_day(value):
    return day_names.index(value) + 1

parser.add_argument(
    '--day',
    type=name_day,
    choices=days,
)
parser.parse_args()

This will result in the following usage message:

usage: example.py [-h] [--day {1,2,3,4,5,6,7}]

This is strange, because the user is expected to enter the day name as a string.

See https://discuss.python.org/t/argparse-unable-to-combine-type-and-choices/88687 for discussion.

CPython versions tested on:

3.10, 3.13

Operating systems tested on:

Linux

Linked PRs

• gh-132558: allow choices to be specified as strings in presence of a type argument  #132743
• gh-132558: add convert_choices parameter to add_argument #133826
• gh-132558: Improve argparse docs on combining type and choices #133827
• [3.14] gh-132558: Improve argparse docs on combining type and choices (GH-133827) #139057
• [3.13] gh-132558: Improve argparse docs on combining type and choices (GH-133827) #139058

[StanFromIreland]

You are converting it to an int with name_day -- hence the problem, I do not see any bug, I guess it could possibly be clarified in the docs.

[hansthen]

I think it is a valid use case if someone wants to use both the type parameter and the options parameter. type is used to convert from the user's vocabulary to the vocabulary of the program. options is used to limit the choices of what the user can enter as program arguments.

Currently that is not possible. A simple fix would be to convert the available options to the user domain before checking.

It is also inconsistent with default which is converted from the user's vocabulary to the program vocabulary.

[ZeroIntensity]

cc @savannahostrowski

[dolfinus]

Why not using Enum instead?

from enum import IntEnum

class DayOfWeek(IntEnum):
  MONDAY = 1
  TUESDAY = 2
  ...

parser.add_argument(
  "--days",
  type=DayOfWeek,  # or other function parsing raw data as enum
  choices=list(DayOfWeek),
)

[hansthen]

Why not using Enum instead?

If I try that I get the following error:

python example3.py --days MO TU
usage: example3.py [-h] [--days {DayOfWeek.MO,DayOfWeek.TU,DayOfWeek.WE,DayOfWeek.TH,DayOfWeek.FR,DayOfWeek.SA,DayOfWeek.SU}]
example3.py: error: argument --days: invalid DayOfWeek value: 'MO'

I saw some examples on SO to adapt this example by also overriding the str and repr method of the Enum. That way it can be used as a workaround in some cases.

However, to clarify, the issue is not just related to int values. It can be any other type such as a choice of dates for instance.

Argparse users should be should be able to do the following things, both independently and in combination.

1. Specify a type function that converts the user input to the appropriate type.
2. Specify a list of choices that constrains the user's input.
3. When displaying help or usage, the choices should be formatted the same way the user should enter them.

[dolfinus]

If I try that I get the following error:

This is because:

>>> DayOfWeek('MONDAY')
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "/home/maxim/.pyenv/versions/3.12.2/lib/python3.12/enum.py", line 744, in __call__
    return cls.__new__(cls, value)
           ^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/maxim/.pyenv/versions/3.12.2/lib/python3.12/enum.py", line 1158, in __new__
    raise ve_exc
ValueError: 'MONDAY' is not a valid DayOfWeek

>>> DayOfWeek(1)
<DayOfWeek.MONDAY: 1>

>>> DayOfWeek['MONDAY']
<DayOfWeek.MONDAY: 1>

So you have to pass to type= some function which parses string input and gives an enum value, like:

parser.add_argument(
  "--days",
  type=lambda val: DayOfWeek[val]
  choices=list(DayOfWeek),
)

I saw some examples on SO to adapt this example by also overriding the str and repr method of the Enum.
When displaying help or usage, the choices should be formatted the same way the user should enter them

You can override Enum __str__ or __repr__ to change the way how the list of possible values is shown in argparse help. But this doesn't affect the way of converting str -> Enum, which is done by type=....

Specify a list of choices that constrains the user's input.

Currently argparse firstly calls parsed = self.type(user_input), and then if parsed in self.choices. You're proposing to change the order of these operations, which apparently is a breaking change.

[StanFromIreland]

is a breaking change.

This has been the order for many years, changing it now will be quite complex and would take a while. I also doubt this will ever be implemented when the work around is simple, just run your choices through your type.

[hansthen]

This has been the order for many years, changing it now will be quite complex and would take a while. I also doubt this will ever be implemented when the work around is simple, just run your choices through your type.

Fair enough. I know it is but a small thing. I thought changing it would not break any existing code, but people may have used the very workaround you suggested.

[StanFromIreland]

This is probably best discussed in the Discourse, if you wish you can open a thread there under Ideas.

Can a triager also please change the labels on this issue, it is a type-feature. @ZeroIntensity maybe you could?:-)