Custom types now display in help text as the name of the parsing function instead of the return type

[daneah]

First Check

• I added a very descriptive title here.
• I used the GitHub search to find a similar question and didn't find it.
• I searched the documentation, with the integrated search.
• I already searched in Google "How to X" and didn't find any information.
• I already read and followed all the tutorials in the docs and didn't find an answer.

Example Code

# example.py

from typing import Annotated

import typer

app = typer.Typer()

class MyCustomType:
    def __init__(self, value: str):
        try:
            self.first, self.second = value.split("/")
        except ValueError:
            raise typer.BadParameter(f"{value} is not in a valid first/second format") from None

def parse_my_custom_type(value: str) -> MyCustomType:
    return MyCustomType(value)

@app.command()
def my_command(arg: Annotated[MyCustomType, typer.Argument(parser=parse_my_custom_type)]) -> None:
    typer.echo(f"First: {arg.first}, Second: {arg.second}")

if __name__ == "__main__":
    app()

Description

Note

The example code requires typer. When you run python example.py --help, notice that the help for arg shows parse_my_custom_type now, instead of the mycustomtype (or maybe it was MYCUSTOMTYPE) that it used to.

Custom types originally showed in the help as the name of the type returned by the parsing function (or perhaps it was the name of the Annotated type of the arg/option).

Recently, this changed such that the arg/option displays the name of the parsing function instead.

Help text generally is about communicating what type of data/values are allowed and what the default value is. For the case of a custom type, it feels like the contract is something like "the supplied value must either be able to be parsed into a valid instance of this custom type, or else it's a bad parameter error." With the parsing function name being shown, it feels more like Typer is showing the implementation details underneath that contract instead.

Operating System

macOS

Operating System Details

No response

Project Version

0.27.0

Python Version

3.14.5

Additional Context

No response

[svlandeg]

Thanks for the report, that doesn't feel quite right. I'll investigate!

[daneah]

Upon looking further, I see that this could partially be a "me" problem, but is maybe still something that could be improved somehow: the parse argument can either take a function or a class that meets the protocol of having a parse method. In some places I was providing the class as the parse argument, and this displayed <TheClass> (or THECLASS in the past) as expected, whereas in others I was providing TheClass.parse as the argument, which unexpectedly (to me) displayed as <parse>.

It makes sense now why this is the case, and I suspect it isn't a regression that was introduced (as noted elsewhere in the discussion). I wonder though if there's an opportunity to lean into principle of least surprise here, so that in both cases I'd get <TheClass>, though I recognize Typer can't handle all possible things. So I'd be good with either marking this as resolved or discussing further if there's any opportunity! Thanks, and sorry for any time/effort wasted.

[svlandeg]

Thanks for reporting back!

I think for now, and to avoid any further breaking behaviour, I'd leave things as is.

[latent-9]

I bisected this against your example. The name shown has been the parser function all along. What changed in 0.27.0 is only how it is rendered, and the new rendering is what makes it read as an implementation detail.

Python 3.14.6, click held constant at 8.4.2 for every row:

typer 0.16.0   |  arg  PARSE_MY_CUSTOM_TYPE      |  Usage: example.py [OPTIONS] ARG
typer 0.17.0   |  arg  PARSE_MY_CUSTOM_TYPE      |  Usage: example.py [OPTIONS] ARG
typer 0.19.2   |  arg  PARSE_MY_CUSTOM_TYPE      |  Usage: example.py [OPTIONS] ARG
typer 0.20.0   |  arg  PARSE_MY_CUSTOM_TYPE      |  Usage: example.py [OPTIONS] ARG
typer 0.23.0   |  arg  PARSE_MY_CUSTOM_TYPE      |  Usage: example.py [OPTIONS] ARG
typer 0.25.0   |  arg  PARSE_MY_CUSTOM_TYPE      |  Usage: example.py [OPTIONS] ARG
typer 0.26.0   |  arg  PARSE_MY_CUSTOM_TYPE      |  Usage: example.py [OPTIONS] ARG
typer 0.26.8   |  arg  PARSE_MY_CUSTOM_TYPE      |  Usage: example.py [OPTIONS] ARG
typer 0.27.0   |  arg  <parse_my_custom_type>    |  Usage: example.py [OPTIONS] {arg}
typer 0.27.1   |  arg  <parse_my_custom_type>    |  Usage: example.py [OPTIONS] {arg}

So the boundary is 0.26.8 to 0.27.0, and MYCUSTOMTYPE was not what any of those versions printed. It was PARSE_MY_CUSTOM_TYPE, which happens to read like a placeholder because of the uppercasing, so the underlying choice was easy not to notice.

The change is the single breaking item in the 0.27.0 notes, "Update metavar printing", PR #1863, in typer/_click/core.py:

 if metavar is None:
-    metavar = self.type.name.upper()
+    type_name = self.type.name
+    if type_name.startswith("<") and type_name.endswith(">"):
+        metavar = type_name
+    else:
+        metavar = f"<{type_name}>"

self.type.name is untouched by that diff. For a parser= argument it comes from typer/main.py:

elif parameter_info.parser is not None:
    return types.FuncParamType(parameter_info.parser)

and FuncParamType.__init__ is self.name = func.__name__. That is the whole chain, and it predates 0.27.0 by a long way.

Your point about the contract still stands, and I think it is sharper than it first looks: .upper() was accidentally load bearing here. PARSE_MY_CUSTOM_TYPE is ambiguous enough to pass for a value placeholder, while <parse_my_custom_type> is unambiguously the callable's name.

Two things I checked that do not help

metavar= is not the lever. It replaces the parameter name column and the usage token, not the type column:

typer.Argument(parser=parse_my_custom_type, metavar="FIRST/SECOND")

 Usage: wa.py b [OPTIONS] {FIRST/SECOND}
 *    FIRST/SECOND      <parse_my_custom_type>  [required]

click_type= with a click.ParamType silently degrades. Typer vendors click, and typer._click.types.ParamType is not click.types.ParamType, so a subclass of the real click base is not recognised as a param type and gets wrapped:

typer.Argument(click_type=MyCustomParamType())   # subclass of click.ParamType
 *    arg      <function>  [required]

Inspecting the built command confirms it: FuncParamType(name='function'). Worth saying clearly that this one is not a 0.27.0 regression. I checked 0.26.8 and it builds the identical FuncParamType(name='function') there too, it just printed as FUNCTION. But since typer/params.py documents typer.Option(click_type=MyParser()) and the annotation resolves to the vendored types.ParamType, it is easy to reach for the public click base and get this.

What does work today

Both verified on 0.27.1:

from typer._click.types import ParamType

class MyCustomParamType(ParamType):
    name = "mycustomtype"
    def convert(self, value, param, ctx):
        try:
            return MyCustomType(value)
        except ValueError:
            self.fail(f"{value} is not in a valid first/second format", param, ctx)

# arg  <mycustomtype>  [required]

or, staying on public API only, renaming the parser:

parse_my_custom_type.__name__ = "mycustomtype"
# arg  <mycustomtype>  [required]

Neither is really a solution. The first reaches into a private module and typer exports no public ParamType (dir(typer) gives BadParameter, CallbackParam, Typer, params), and the second is a workaround dressed as a rename. If the conclusion is that parser= should name the annotated type rather than the callable, that would be a change in get_click_type rather than in the metavar printing.

[latent-9]

A minimal fix that keeps the parser= chain intact: have FuncParamType derive its name from the parser's return annotation when there is one, and fall back to func.__name__.

try:
    ret = typing.get_type_hints(func).get("return")
except Exception:
    ret = None
self.name = getattr(ret, "__name__", None) or func.__name__

For the example that turns <parse_my_custom_type> back into <MyCustomType>, the return type daneah expected, and it is a no-op for parsers with no return annotation. Happy to open a PR if you want to go this route.

[svlandeg]

What is "seriously?" supposed to mean, in response to my question whether the reply was AI generated?

Also no, don't open a PR at this point in time. Especially if you haven't read the contribution guidelines yet.

[latent-9]

Sorry about that, the "seriously?" was a slip and not aimed at you. Understood, I will not open a PR. I will read the contribution guidelines first. Thanks for looking into it.

[latent-9]

Yeah no worries, glad it makes sense now. That is exactly it: the class keeps its own name, but a bound method keeps the method name, so the two render differently. Getting both to land on <TheClass> for least surprise would be nice. Clean repro btw.

[daneah]

^ (This is a reply to my comment in the other thread, I think)