TypeError when argument help is a lazy str proxy

[bckohan]

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

import typer
import typing as t


# e.g. Django's gettext_lazy proxies: not a str, but delegate str methods
class LazyStr:
    def __init__(self, value: str) -> None:
        self._value = value

    def __str__(self) -> str:
        return self._value

    def __getattr__(self, name: str) -> t.Any:
        return getattr(self._value, name)

app = typer.Typer(rich_markup_mode=None)

@app.command()
def main(
    name: t.Annotated[
        str, typer.Argument(help=LazyStr("Lazy argument help"), show_default=False)
    ] = "default",
    opt: t.Annotated[str, typer.Option(help=LazyStr("Lazy option help"))] = "x",
):
    pass  # pragma: no cover

Description

Trying to clean up this old issue in django-typer

Django uses lazy translation wrappers to defer translation until after the translation system is bootstrapped. This means you often find devs passing gettext_lazy into command help strings.

By accident this works for options because inspect.cleandoc() coerces help strings and is called on construction:

typer/typer/core.py

Lines 479 to 480 in 82b8395

	if help:
	help = inspect.cleandoc(help)

The TyperArgument constructor does not do this:

typer/typer/core.py

Lines 279 to 280 in 82b8395

	self.help = help
	self.show_default = show_default

I've been allowing gettext_lazy in Argument strings in django-typer by directly monkey patching the offending call. The actual crash only occurs when rich_markup_mode=None because help formatting goes through the vendored click formatter instead. That path does write_dl → measure_table → term_len → strip_ansi, which runs a compiled regex directly on the object:

File ".../typer/_click/_compat.py", line 441, in strip_ansi
    return _ansi_re.sub("", value)
TypeError: expected string or bytes-like object, got 'LazyStr'

I don't think coercing in this strip_ansi call is is the correct solution though, nor do I think cleandoc symmetry with Option in Argument is correct either. First, resolving the translation at TyperOption instantiation time means at command module import time. Usually this will happen after Django's bootstrapped the translation infra, but in weird edge cases like when pulling in code to sphinx or whatnot it might not resulting in unexpected crashes.

I think the deeper fix is to recognize that lazy str objects are a potential input to helps and add something like this to the Typer contract:

Help strings will always be coerced to str, but at render time, not before.

I wouldn't be surprised if this issue surfaces elsewhere and a statement like this is clear and verifiable in CI. Thoughts? Happy to create a PR.

One way to fix this with TyperOption and TyperArgument might be to convert help into a lazy property:

self._help = help

@property
def help(self) -> str | None:
    return inspect.cleandoc(str(self._help)) if self._help else None

Operating System

macOS

Operating System Details

No response

Project Version

0.27.2

Python Version

3.14

Additional Context

No response

[svlandeg]

I'm trying to understand what exactly you're proposing. So in that scenario, TyperArgument and TyperOption wouldn't have a help: str | None = None in their constructor anymore? But a more loosely typed _help? Or both?

[bckohan]

I'm not suggesting the type hints need to change. I'm suggesting Typer's contract guarantee str coercion both happens and happens at render-time before any native str operations take place. This will allow any manner of proxy str object to pass in reliably - a lazy translation being one example use case.

Right now str coercion happens on every path but for Arguments when rich_markup_mode=None. For other paths it often happens in constructors which tend to run at module import time. This means str proxies work in some cases but not others and results are unpredictable.

This is admittedly an esoteric use case. I only suggest the contract because it would make things generally tidier unlike most esoterica. (while also allowing me to remove a monkey patch 😉)

[svlandeg]

@CAOShurong: please stop adding AI generated replies to the discussions, thanks.