Experimental Union Support (Request for a Pull Request)

[hsaeed3]

FORK / BRANCH LOCATION: HERE

Upon the tears of many who had fallen before (such as the valiant efforts of PR #1719), I too yearned as a child for union annotation support within typer.

I've created a fork and implementation for union support, which currently passes all requirements for a valid pull request, but as the template mentions, I wanted to ensure everything was put together properly before opening a PR.

Problem

The goal was to provide union support in the least invasive manner possible while providing a centralized location to access and modify all associated logic.

Today, something like value: int | str fails unless it collapses to a single non-None member (e.g. int | None). That's a sensible default, but it blocks a common CLI pattern: accept a numeric id or a slug, a Literal choice or a freeform string, and so on.

Approaches Considered

1. experimental_union_types on typer.Typer() — way too broad; one switch for the whole app.

app = typer.Typer(experimental_union_types=True)

2. union_type: bool on Option() / Argument() — union-ness belongs to the annotation, not each parameter declaration. (Felt finicky to me from a developer's perspective, but I do have a relatively complete implementation in this pattern that can replace the current content of the branch.

@app.command()
def some_command(name: str | int = typer.Argument(..., union_type=True)

3. union_types=True on @app.command() / @app.callback() — what I landed on: opt-in per command, logic centralized in a single internal module.

@app.command(union_types=True)
def main(item_id: int | str):
    ...

int | None and similar single-member optionals keep working as they do today—no flag needed.

Branch Content

The feature functionality itself is centralized within typer/_union_types.py and requires at the moment minimal intersection with only the typer/main.py module.

• Union parsing, help/metavars, and error messages via a dedicated helper module
• Shell autocomplete across union members
• Shell error & missing messages show choices in readable structure similar to Literal
• Tests with 100% coverage on the helper typer/_union_types.py (still room to compact the implementation itself)
• Docs with "termy" runtime examples for help, completion, and errors

Nested unions and list/tuple members are out of scope for now.

Further Questions

1. Is union_types=True on command() / callback() the right opt-in surface?
2. Do any changes need to be made before a PR can be opened?
3. Is the 'experimental' naming convention appropriate enough for this context.

[svlandeg]

Hi @hsaeed3! Thanks for opening the discussion and for the detailed proposal.

At this point in time, it wouldn't be a good idea to open a PR for this, as we're actively working on refactoring type resolvement in Typer. You'd inevitably end up with (a lot of) conflicts with that ongoing work. At this point we're trying to move this forward with the core maintainer's team, and once it's stable we'll definitely welcome further feedback/improvements on it.

Your point about union support is definitely valid though, and we'll keep this in mind as we continue our refactor as well 🙏 . Will update here if there's more concrete news!

[hsaeed3]

bless your soul, you can close this discussion if needed as long as hope is alive

[svlandeg]

Let's keep it open, it's a valid feature request, as long as it doesn't attract LLM slop 😉