✨ Add module:function syntax support for typer CLI

[lmmx]

Adds support for specifying functions directly using colon syntax in the typer CLI, as used in pyproject console scripts entrypoint syntax, and projects like uvicorn/gunicorn.

Described in discussion #1274

Before:

$ typer 'autocli.one:step_1' run 123
Not a valid file or Python module: autocli.one:step_1

$ typer --func=step_1 'autocli.one' run 123  # Required explicit --func flag
Step 1: Processing with a=123, result=processed_123.txt

After:

$ typer 'autocli.one:step_1' run 123
Step 1: Processing with a=123, result=processed_123.txt

$ typer 'path/to/file.py:step_1' run 123  # Also works with file paths
Step 1: Processing with a=123, result=processed_123.txt

The change is pretty minimal - 4 lines added to maybe_update_state() to parse the colon syntax and set the function parameter on the click Context params dict which is then picked up in the existing part of the function afterwards.

Changes:

• Feature: Parse "module:function" and "/path/to/file.py:function" syntax in typer.cli:maybe_update_state
• Tests: Add coverage of both module and file path variants
• Docs: Updated tutorial with examples

[lmmx]

Not sure why CI failed, maybe it needs a label added (triage)? Let me know if I can assist 👍

[lmmx]

Rebased to update with trunk, all checks passed 😄

[github-actions]

📝 Docs preview for commit 88b4ffb at: https://d829fb58.typertiangolo.pages.dev

Modified Pages

• https://d829fb58.typertiangolo.pages.dev/tutorial/typer-command/ - (before)

[lmmx]

Great, this looks ready @svlandeg 😄

[svlandeg]

Thanks @lmmx! I'll try and review this soonish.

[svlandeg]

Wouldn't this break the use-case where Windows users specify a full path with C:\somepath?

[lmmx]

Oh great catch ! Yes we can check that, very good

import os

def maybe_update_state(ctx: click.Context) -> None:
    path_or_module = ctx.params.get("path_or_module")
    if path_or_module and ":" in path_or_module:
        drive, _ = os.path.splitdrive(path_or_module)
        if not drive:  # avoid misinterpreting "C:\..." on Windows
            module_part, func_part = path_or_module.rsplit(":", 1)
            path_or_module = module_part
            ctx.params.update({"func": func_part})
    ctx.params["path_or_module"] = path_or_module

Hmm and I’d add an OS check to that condition gate too

[svlandeg]

Thanks for your work on this @lmmx!

I've thought about this for a bit, and to be completely honest I'm a little on the fence about having this feature. Mostly because there is already a valid way to achieve what you want. While I can see the appeal of using the : syntax, that also makes the code more verbose and error-prone, as exemplified by the fact that we need to think specifically about Windows paths etc.

I'll solicit feedback from Tiangolo to get his opinion. If he does want to support this, we'll still need to make sure the edits for the Window paths get added & tested.