From 30fcad507820ab67c5acfbbfa81d26dfbe1f75fe Mon Sep 17 00:00:00 2001 From: Patrick Arminio Date: Mon, 18 Nov 2024 13:28:44 +0000 Subject: [PATCH 01/10] TMP: alwasy return none when getting group name --- typer/main.py | 22 +++++++++++----------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/typer/main.py b/typer/main.py index 55d865c780..9907c6fc61 100644 --- a/typer/main.py +++ b/typer/main.py @@ -390,17 +390,17 @@ def get_command(typer_instance: Typer) -> click.Command: def get_group_name(typer_info: TyperInfo) -> Optional[str]: - if typer_info.callback: - # Priority 1: Callback passed in app.add_typer() - return get_command_name(typer_info.callback.__name__) - if typer_info.typer_instance: - registered_callback = typer_info.typer_instance.registered_callback - if registered_callback: - if registered_callback.callback: - # Priority 2: Callback passed in @subapp.callback() - return get_command_name(registered_callback.callback.__name__) - if typer_info.typer_instance.info.callback: - return get_command_name(typer_info.typer_instance.info.callback.__name__) + # if typer_info.callback: + # # Priority 1: Callback passed in app.add_typer() + # return get_command_name(typer_info.callback.__name__) + # if typer_info.typer_instance: + # registered_callback = typer_info.typer_instance.registered_callback + # if registered_callback: + # if registered_callback.callback: + # # Priority 2: Callback passed in @subapp.callback() + # return get_command_name(registered_callback.callback.__name__) + # if typer_info.typer_instance.info.callback: + # return get_command_name(typer_info.typer_instance.info.callback.__name__) return None From 31160fba3f5bc9f21d01777dd9ad66323655fd67 Mon Sep 17 00:00:00 2001 From: Patrick Arminio Date: Mon, 18 Nov 2024 13:41:18 +0000 Subject: [PATCH 02/10] Update tutorials to always have a name --- docs_src/subcommands/name_help/tutorial002.py | 2 +- docs_src/subcommands/name_help/tutorial003.py | 2 +- docs_src/subcommands/name_help/tutorial004.py | 2 +- docs_src/subcommands/name_help/tutorial005.py | 4 ++-- 4 files changed, 5 insertions(+), 5 deletions(-) diff --git a/docs_src/subcommands/name_help/tutorial002.py b/docs_src/subcommands/name_help/tutorial002.py index df48e075d4..ae9f1036b5 100644 --- a/docs_src/subcommands/name_help/tutorial002.py +++ b/docs_src/subcommands/name_help/tutorial002.py @@ -3,7 +3,7 @@ app = typer.Typer() users_app = typer.Typer() -app.add_typer(users_app) +app.add_typer(users_app, name="users") @users_app.callback() diff --git a/docs_src/subcommands/name_help/tutorial003.py b/docs_src/subcommands/name_help/tutorial003.py index c24d0e187f..b6c10857dc 100644 --- a/docs_src/subcommands/name_help/tutorial003.py +++ b/docs_src/subcommands/name_help/tutorial003.py @@ -9,7 +9,7 @@ def users(): """ -users_app = typer.Typer(callback=users) +users_app = typer.Typer(callback=users, name="users") app.add_typer(users_app) diff --git a/docs_src/subcommands/name_help/tutorial004.py b/docs_src/subcommands/name_help/tutorial004.py index 92fbc376aa..f1f5aed5c0 100644 --- a/docs_src/subcommands/name_help/tutorial004.py +++ b/docs_src/subcommands/name_help/tutorial004.py @@ -10,7 +10,7 @@ def old_callback(): users_app = typer.Typer(callback=old_callback) -app.add_typer(users_app) +app.add_typer(users_app, name="users") @users_app.callback() diff --git a/docs_src/subcommands/name_help/tutorial005.py b/docs_src/subcommands/name_help/tutorial005.py index 6cedabfef4..50730171d7 100644 --- a/docs_src/subcommands/name_help/tutorial005.py +++ b/docs_src/subcommands/name_help/tutorial005.py @@ -9,7 +9,7 @@ def old_callback(): """ -users_app = typer.Typer(callback=old_callback) +users_app = typer.Typer(callback=old_callback, name="users") def new_users(): @@ -18,7 +18,7 @@ def new_users(): """ -app.add_typer(users_app, callback=new_users) +app.add_typer(users_app, callback=new_users, name="new-users") @users_app.callback() From 95d2208418ff958abb0b16f00f8b5243cf77831e Mon Sep 17 00:00:00 2001 From: Patrick Arminio Date: Tue, 19 Nov 2024 10:54:13 +0000 Subject: [PATCH 03/10] Remove code and update docs --- docs/tutorial/subcommands/name-and-help.md | 40 +++++++++------------- typer/main.py | 17 --------- 2 files changed, 16 insertions(+), 41 deletions(-) diff --git a/docs/tutorial/subcommands/name-and-help.md b/docs/tutorial/subcommands/name-and-help.md index 47eced3dd3..1cc6f34926 100644 --- a/docs/tutorial/subcommands/name-and-help.md +++ b/docs/tutorial/subcommands/name-and-help.md @@ -81,23 +81,15 @@ def create(item: str): ...will create a command `create` with a help text of `Create an item`. -### Inferring name and help from `@app.callback()` +### Inferring help from `@app.callback()` The same way, if you define a callback in a `typer.Typer()`, the help text is extracted from the callback function's docstring. -And if that Typer app is added to another Typer app, the default name of the command is generated from the name of the callback function. - Here's an example: {* docs_src/subcommands/name_help/tutorial002.py hl[6,9,10,11,12,13] *} -Notice that now we added the sub-Typer without specifying a `name` nor a `help`. - -They are now inferred from the callback function. - -The command name will be the same callback function's name: `users`. - -And the help text for that `users` command will be the callback function's docstring: `Manage users in the app.`. +The help text for that command will be the callback function's docstring: `Manage users in the app.`. Check it: @@ -107,7 +99,7 @@ Check it: // Check the main help $ python main.py --help -// Notice the command name "users" and the help text "Manage users in the app." +// Notice the help text "Manage users in the app." Usage: main.py [OPTIONS] COMMAND [ARGS]... Options: @@ -135,9 +127,9 @@ Commands: -### Name and help from callback parameter in `typer.Typer()` +### Help from callback parameter in `typer.Typer()` -If you pass a `callback` parameter while creating a `typer.Typer(callback=some_function)` it will be used to infer the name and help text. +If you pass a `callback` parameter while creating a `typer.Typer(callback=some_function)` it will be used to infer the help text. This has the lowest priority, we'll see later what has a higher priority and can override it. @@ -155,7 +147,7 @@ Check it: // Check the main help $ python main.py --help -// Notice the command name "users" and the help text "Manage users in the app." +// Notice the help text "Manage users in the app." Usage: main.py [OPTIONS] COMMAND [ARGS]... Options: @@ -185,11 +177,11 @@ Commands: ### Override a callback set in `typer.Typer()` with `@app.callback()` -The same as with normal **Typer** apps, if you pass a `callback` to `typer.Typer(callback=some_function)` and then override it with `@app.callback()`, the name and help text will be inferred from the new callback: +The same as with normal **Typer** apps, if you pass a `callback` to `typer.Typer(callback=some_function)` and then override it with `@app.callback()`, the help text will be inferred from the new callback: {* docs_src/subcommands/name_help/tutorial004.py hl[16,17,18,19,20] *} -Now the name of the command will be `users` instead of `old-callback`, and the help text will be `Manage users in the app.` instead of `Old callback help.`. +Now the help text will be `Manage users in the app.` instead of `Old callback help.`. Check it: @@ -199,7 +191,7 @@ Check it: // Check the main help $ python main.py --help -// Notice the command name "users" and the help text "Manage users in the app." +// Notice the help text "Manage users in the app." Usage: main.py [OPTIONS] COMMAND [ARGS]... Options: @@ -227,17 +219,17 @@ Commands: -### Infer name and help from callback in `app.add_typer()` +### Help from callback in `app.add_typer()` -If you override the callback in `app.add_typer()` when including a sub-app, the name and help will be inferred from this callback function. +If you override the callback in `app.add_typer()` when including a sub-app, the help will be inferred from this callback function. -This takes precedence over inferring the name and help from a callback set in `@sub_app.callback()` and `typer.Typer(callback=sub_app_callback)`. +This takes precedence over inferring the help from a callback set in `@sub_app.callback()` and `typer.Typer(callback=sub_app_callback)`. Check the code: {* docs_src/subcommands/name_help/tutorial005.py hl[15,16,17,18,21] *} -Now the command will be `new-users` instead of `users`. And the help text will be `I have the highland! Create some users.` instead of the previous ones. +The help text will be `I have the highland! Create some users.` instead of the previous ones. Check it: @@ -277,13 +269,13 @@ Commands: ### Enough inferring -So, when inferring a name and help text, the precedence order from lowest priority to highest is: +So, when inferring help text, the precedence order from lowest priority to highest is: * `sub_app = typer.Typer(callback=some_function)` * `@sub_app.callback()` * `app.add_typer(sub_app, callback=new_function)` -That's for inferring the name and help text from functions. +That's for inferring the help text from functions. But if you set the name and help text explicitly, that has a higher priority than these. @@ -299,7 +291,7 @@ Setting the name and help text explicitly always has a higher precedence than in ### Name and help in `typer.Typer()` -You could have all the callbacks and overrides we defined before, but the name and help text was inferred from the function name and docstring. +You could have all the callbacks and overrides we defined before, but the help text was inferred from the function docstring. If you set it explicitly, that takes precedence over inferring. diff --git a/typer/main.py b/typer/main.py index 9907c6fc61..86a46f9713 100644 --- a/typer/main.py +++ b/typer/main.py @@ -389,21 +389,6 @@ def get_command(typer_instance: Typer) -> click.Command: ) # pragma: no cover -def get_group_name(typer_info: TyperInfo) -> Optional[str]: - # if typer_info.callback: - # # Priority 1: Callback passed in app.add_typer() - # return get_command_name(typer_info.callback.__name__) - # if typer_info.typer_instance: - # registered_callback = typer_info.typer_instance.registered_callback - # if registered_callback: - # if registered_callback.callback: - # # Priority 2: Callback passed in @subapp.callback() - # return get_command_name(registered_callback.callback.__name__) - # if typer_info.typer_instance.info.callback: - # return get_command_name(typer_info.typer_instance.info.callback.__name__) - return None - - def solve_typer_info_help(typer_info: TyperInfo) -> str: # Priority 1: Explicit value was set in app.add_typer() if not isinstance(typer_info.help, DefaultPlaceholder): @@ -480,8 +465,6 @@ def solve_typer_info_defaults(typer_info: TyperInfo) -> TyperInfo: pass # Value not set, use the default values[name] = value.value - if values["name"] is None: - values["name"] = get_group_name(typer_info) values["help"] = solve_typer_info_help(typer_info) return TyperInfo(**values) From 34e1bf77964a87bde743854c2576a2aafc2da4dd Mon Sep 17 00:00:00 2001 From: Patrick Arminio Date: Tue, 19 Nov 2024 15:45:06 +0000 Subject: [PATCH 04/10] Update docs --- docs/tutorial/subcommands/name-and-help.md | 26 ++++++++++++------- docs_src/subcommands/name_help/tutorial007.py | 1 + 2 files changed, 17 insertions(+), 10 deletions(-) diff --git a/docs/tutorial/subcommands/name-and-help.md b/docs/tutorial/subcommands/name-and-help.md index 1cc6f34926..8b324439d4 100644 --- a/docs/tutorial/subcommands/name-and-help.md +++ b/docs/tutorial/subcommands/name-and-help.md @@ -10,7 +10,7 @@ app.add_typer(users.app, name="users") ## Add a help text -We can also set the `help` while adding a Typer: +We can also set the `help` text while adding a Typer: {* docs_src/subcommands/name_help/tutorial001.py hl[6] *} @@ -60,9 +60,9 @@ But those are documented later in another section. /// -## Inferring name and help from callback +## Inferring help text from callback -### Inferring a command's name and help +### Inferring a command's help text When you create a command with `@app.command()`, by default, it generates the name from the function name. @@ -81,13 +81,13 @@ def create(item: str): ...will create a command `create` with a help text of `Create an item`. -### Inferring help from `@app.callback()` +### Inferring the help text from `@app.callback()` The same way, if you define a callback in a `typer.Typer()`, the help text is extracted from the callback function's docstring. Here's an example: -{* docs_src/subcommands/name_help/tutorial002.py hl[6,9,10,11,12,13] *} +{* docs_src/subcommands/name_help/tutorial002.py hl[9,10,11,12,13] *} The help text for that command will be the callback function's docstring: `Manage users in the app.`. @@ -127,6 +127,12 @@ Commands: +/// note + +In previous versions of Typer, in addition to the help text, the command name was also inferred from the callback function name, this is no longer the case. + +/// + ### Help from callback parameter in `typer.Typer()` If you pass a `callback` parameter while creating a `typer.Typer(callback=some_function)` it will be used to infer the help text. @@ -277,7 +283,7 @@ So, when inferring help text, the precedence order from lowest priority to highe That's for inferring the help text from functions. -But if you set the name and help text explicitly, that has a higher priority than these. +But if you set the help text explicitly, that has a higher priority than these. ## Set the name and help @@ -345,7 +351,7 @@ Commands: -### Name and help in `@app.callback()` +### Help text in `@app.callback()` Any parameter that you use when creating a `typer.Typer()` app can be overridden in the parameters of `@app.callback()`. @@ -439,9 +445,9 @@ Commands: The precedence to generate a command's name and help, from lowest priority to highest, is: -* Implicitly inferred from `sub_app = typer.Typer(callback=some_function)` -* Implicitly inferred from the callback function under `@sub_app.callback()` -* Implicitly inferred from `app.add_typer(sub_app, callback=some_function)` +* Implicitly inferred from `sub_app = typer.Typer(callback=some_function)` (only the help text) +* Implicitly inferred from the callback function under `@sub_app.callback()` (only the help text) +* Implicitly inferred from `app.add_typer(sub_app, callback=some_function)` (only the help text) * Explicitly set on `sub_app = typer.Typer(name="some-name", help="Some help.")` * Explicitly set on `@sub_app.callback("some-name", help="Some help.")` * Explicitly set on `app.add_typer(sub_app, name="some-name", help="Some help.")` diff --git a/docs_src/subcommands/name_help/tutorial007.py b/docs_src/subcommands/name_help/tutorial007.py index 15544d89ee..c42ec5fe75 100644 --- a/docs_src/subcommands/name_help/tutorial007.py +++ b/docs_src/subcommands/name_help/tutorial007.py @@ -21,6 +21,7 @@ def new_users(): app.add_typer(users_app, callback=new_users) +# TODO: do we want this to work? @users_app.callback("call-users", help="Help from callback for users.") def users(): """ From 31e23ece573c928b312bfa2663b08891336ed98e Mon Sep 17 00:00:00 2001 From: Patrick Arminio Date: Wed, 20 Nov 2024 11:44:50 +0000 Subject: [PATCH 05/10] Remove `name` parameter from `callback` --- docs/tutorial/subcommands/name-and-help.md | 1 - docs_src/subcommands/name_help/tutorial007.py | 3 +-- docs_src/subcommands/name_help/tutorial008.py | 2 +- .../test_subcommands/test_name_help/test_tutorial007.py | 2 +- typer/main.py | 2 -- 5 files changed, 3 insertions(+), 7 deletions(-) diff --git a/docs/tutorial/subcommands/name-and-help.md b/docs/tutorial/subcommands/name-and-help.md index 8b324439d4..1b070b2401 100644 --- a/docs/tutorial/subcommands/name-and-help.md +++ b/docs/tutorial/subcommands/name-and-help.md @@ -449,7 +449,6 @@ The precedence to generate a command's name and help, from lowest priority to hi * Implicitly inferred from the callback function under `@sub_app.callback()` (only the help text) * Implicitly inferred from `app.add_typer(sub_app, callback=some_function)` (only the help text) * Explicitly set on `sub_app = typer.Typer(name="some-name", help="Some help.")` -* Explicitly set on `@sub_app.callback("some-name", help="Some help.")` * Explicitly set on `app.add_typer(sub_app, name="some-name", help="Some help.")` So, `app.add_typer(sub_app, name="some-name", help="Some help.")` always wins. diff --git a/docs_src/subcommands/name_help/tutorial007.py b/docs_src/subcommands/name_help/tutorial007.py index c42ec5fe75..68baa06215 100644 --- a/docs_src/subcommands/name_help/tutorial007.py +++ b/docs_src/subcommands/name_help/tutorial007.py @@ -21,8 +21,7 @@ def new_users(): app.add_typer(users_app, callback=new_users) -# TODO: do we want this to work? -@users_app.callback("call-users", help="Help from callback for users.") +@users_app.callback(help="Help from callback for users.") def users(): """ Manage users in the app. diff --git a/docs_src/subcommands/name_help/tutorial008.py b/docs_src/subcommands/name_help/tutorial008.py index 1063da2b7a..ddfc265051 100644 --- a/docs_src/subcommands/name_help/tutorial008.py +++ b/docs_src/subcommands/name_help/tutorial008.py @@ -26,7 +26,7 @@ def new_users(): ) -@users_app.callback("call-users", help="Help from callback for users.") +@users_app.callback(help="Help from callback for users.") def users(): """ Manage users in the app. diff --git a/tests/test_tutorial/test_subcommands/test_name_help/test_tutorial007.py b/tests/test_tutorial/test_subcommands/test_name_help/test_tutorial007.py index 3935dee2da..b045e618ce 100644 --- a/tests/test_tutorial/test_subcommands/test_name_help/test_tutorial007.py +++ b/tests/test_tutorial/test_subcommands/test_name_help/test_tutorial007.py @@ -14,7 +14,7 @@ def test_help(): result = runner.invoke(app, ["--help"]) assert result.exit_code == 0 assert "Commands" in result.output - assert "call-users" in result.output + assert "users" in result.output assert "Help from callback for users." in result.output diff --git a/typer/main.py b/typer/main.py index 86a46f9713..edb3544060 100644 --- a/typer/main.py +++ b/typer/main.py @@ -184,7 +184,6 @@ def __init__( def callback( self, - name: Optional[str] = Default(None), *, cls: Optional[Type[TyperGroup]] = Default(None), invoke_without_command: bool = Default(False), @@ -206,7 +205,6 @@ def callback( ) -> Callable[[CommandFunctionType], CommandFunctionType]: def decorator(f: CommandFunctionType) -> CommandFunctionType: self.registered_callback = TyperInfo( - name=name, cls=cls, invoke_without_command=invoke_without_command, no_args_is_help=no_args_is_help, From 600ec874bb48ac6e3e8bd5a737c3b8b7d0d8e405 Mon Sep 17 00:00:00 2001 From: svlandeg Date: Mon, 25 Nov 2024 15:42:46 +0100 Subject: [PATCH 06/10] fix tutorial007 unit test --- docs_src/subcommands/name_help/tutorial007.py | 2 +- .../test_subcommands/test_name_help/test_tutorial007.py | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/docs_src/subcommands/name_help/tutorial007.py b/docs_src/subcommands/name_help/tutorial007.py index 68baa06215..fcac500ab1 100644 --- a/docs_src/subcommands/name_help/tutorial007.py +++ b/docs_src/subcommands/name_help/tutorial007.py @@ -18,7 +18,7 @@ def new_users(): """ -app.add_typer(users_app, callback=new_users) +app.add_typer(users_app, callback=new_users, name="users") @users_app.callback(help="Help from callback for users.") diff --git a/tests/test_tutorial/test_subcommands/test_name_help/test_tutorial007.py b/tests/test_tutorial/test_subcommands/test_name_help/test_tutorial007.py index b045e618ce..f0632fb5eb 100644 --- a/tests/test_tutorial/test_subcommands/test_name_help/test_tutorial007.py +++ b/tests/test_tutorial/test_subcommands/test_name_help/test_tutorial007.py @@ -19,13 +19,13 @@ def test_help(): def test_command_help(): - result = runner.invoke(app, ["call-users", "--help"]) + result = runner.invoke(app, ["users", "--help"]) assert result.exit_code == 0 assert "Help from callback for users." in result.output def test_command(): - result = runner.invoke(app, ["call-users", "create", "Camila"]) + result = runner.invoke(app, ["users", "create", "Camila"]) assert result.exit_code == 0 assert "Creating user: Camila" in result.output From 38f064fb58bcf4a3a3c6ca35fb4d2cd8fc65eb7c Mon Sep 17 00:00:00 2001 From: Patrick Arminio Date: Wed, 27 Nov 2024 14:41:45 +0000 Subject: [PATCH 07/10] Add warning --- tests/test_callback_warning.py | 44 ++++++++++++++++++++++++++++++++++ typer/main.py | 7 ++++++ 2 files changed, 51 insertions(+) create mode 100644 tests/test_callback_warning.py diff --git a/tests/test_callback_warning.py b/tests/test_callback_warning.py new file mode 100644 index 0000000000..af2d9724f1 --- /dev/null +++ b/tests/test_callback_warning.py @@ -0,0 +1,44 @@ +import pytest +import typer +from typer.testing import CliRunner + +runner = CliRunner() + + +def test_warns_when_callback_is_not_supported(): + app = typer.Typer() + + sub_app = typer.Typer() + + @sub_app.callback() + def callback(): + """This help text is not used.""" + + app.add_typer(sub_app) + + with pytest.warns( + match="The 'callback' parameter is not supported by Typer when using `add_typer` without a name" + ): + try: + app() + except SystemExit: + pass + + +def test_warns_when_callback_is_not_supported_added_after_add_typer(): + app = typer.Typer() + + sub_app = typer.Typer() + app.add_typer(sub_app) + + @sub_app.callback() + def callback(): + """This help text is not used.""" + + with pytest.warns( + match="The 'callback' parameter is not supported by Typer when using `add_typer` without a name" + ): + try: + app() + except SystemExit: + pass diff --git a/typer/main.py b/typer/main.py index edb3544060..133e47359f 100644 --- a/typer/main.py +++ b/typer/main.py @@ -493,6 +493,13 @@ def get_group_from_info( ) if sub_group.name: commands[sub_group.name] = sub_group + elif sub_group.callback: + import warnings + + warnings.warn( + "The 'callback' parameter is not supported by Typer when using `add_typer` without a name", + stacklevel=2, + ) solved_info = solve_typer_info_defaults(group_info) ( params, From 53f65ba01df4ce5dcbb36befc1da766ced67ba64 Mon Sep 17 00:00:00 2001 From: Patrick Arminio Date: Wed, 27 Nov 2024 14:43:08 +0000 Subject: [PATCH 08/10] Add warning when callback is passed but name is None --- typer/main.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/typer/main.py b/typer/main.py index 133e47359f..a23c3c0f5d 100644 --- a/typer/main.py +++ b/typer/main.py @@ -498,7 +498,7 @@ def get_group_from_info( warnings.warn( "The 'callback' parameter is not supported by Typer when using `add_typer` without a name", - stacklevel=2, + stacklevel=5, ) solved_info = solve_typer_info_defaults(group_info) ( From ff6a3efd5d09afd187ed28275d140676682879f4 Mon Sep 17 00:00:00 2001 From: Patrick Arminio Date: Wed, 27 Nov 2024 15:35:06 +0000 Subject: [PATCH 09/10] Update docs --- docs/tutorial/subcommands/name-and-help.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/tutorial/subcommands/name-and-help.md b/docs/tutorial/subcommands/name-and-help.md index 1b070b2401..7465961b50 100644 --- a/docs/tutorial/subcommands/name-and-help.md +++ b/docs/tutorial/subcommands/name-and-help.md @@ -129,7 +129,7 @@ Commands: /// note -In previous versions of Typer, in addition to the help text, the command name was also inferred from the callback function name, this is no longer the case. +Until Typer 0.14.0, in addition to the help text, the command name was also inferred from the callback function name, this is no longer the case. /// From 28f7d3604439e33d570cd3eb0b6dbac83f879785 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Sebasti=C3=A1n=20Ram=C3=ADrez?= Date: Thu, 28 Nov 2024 22:42:55 +0100 Subject: [PATCH 10/10] =?UTF-8?q?=F0=9F=93=9D=20Tweak=20docs=20and=20examp?= =?UTF-8?q?le=20for=20setting=20help=20and=20name?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/tutorial/subcommands/name-and-help.md | 41 +++++++++++-------- docs_src/subcommands/name_help/tutorial007.py | 4 +- 2 files changed, 25 insertions(+), 20 deletions(-) diff --git a/docs/tutorial/subcommands/name-and-help.md b/docs/tutorial/subcommands/name-and-help.md index 7465961b50..b50fc6db74 100644 --- a/docs/tutorial/subcommands/name-and-help.md +++ b/docs/tutorial/subcommands/name-and-help.md @@ -48,7 +48,7 @@ Commands: -We can set the `name` and `help` in several places, each one taking precedence over the other, overriding the previous value. +We can set the `help` in several places, each one taking precedence over the other, overriding the previous value. Let's see those locations. @@ -129,7 +129,7 @@ Commands: /// note -Until Typer 0.14.0, in addition to the help text, the command name was also inferred from the callback function name, this is no longer the case. +Before Typer 0.14.0, in addition to the help text, the command name was also inferred from the callback function name, this is no longer the case. /// @@ -291,7 +291,7 @@ Let's now see the places where you can set the command name and help text, from /// tip -Setting the name and help text explicitly always has a higher precedence than inferring from a callback function. +Setting the help text explicitly always has a higher precedence than inferring from a callback function. /// @@ -311,7 +311,7 @@ The rest of the callbacks and overrides are there only to show you that they don /// -We set an explicit name `exp-users`, and an explicit help `Explicit help.`. +We set an explicit help `Explicit help.`. So that will take precedence now. @@ -353,13 +353,13 @@ Commands: ### Help text in `@app.callback()` -Any parameter that you use when creating a `typer.Typer()` app can be overridden in the parameters of `@app.callback()`. +Many parameters that you use when creating a `typer.Typer()` app can be overridden in the parameters of `@app.callback()`. -Continuing with the previous example, we now override the values in `@user_app.callback()`: +Continuing with the previous example, we now override the `help` in `@user_app.callback()`: {* docs_src/subcommands/name_help/tutorial007.py hl[24] *} -And now the command name will be `call-users` and the help text will be `Help from callback for users.`. +And now the help text will be `Help from callback for users.`. Check it: @@ -369,7 +369,7 @@ Check it: // Check the help $ python main.py --help -// The command name now is call-users and the help text is "Help from callback for users.". +// The help text is now "Help from callback for users.". Usage: main.py [OPTIONS] COMMAND [ARGS]... Options: @@ -378,13 +378,13 @@ Options: --help Show this message and exit. Commands: - call-users Help from callback for users. + users Help from callback for users. -// Check the call-users command help -$ python main.py call-users --help +// Check the users command help +$ python main.py users --help // Notice the main help text -Usage: main.py call-users [OPTIONS] COMMAND [ARGS]... +Usage: main.py users [OPTIONS] COMMAND [ARGS]... Help from callback for users. @@ -443,12 +443,17 @@ Commands: ## Recap -The precedence to generate a command's name and help, from lowest priority to highest, is: +The precedence to generate a command's **help**, from lowest priority to highest, is: + +* Implicitly inferred from `sub_app = typer.Typer(callback=some_function)` +* Implicitly inferred from the callback function under `@sub_app.callback()` +* Implicitly inferred from `app.add_typer(sub_app, callback=some_function)` +* Explicitly set on `sub_app = typer.Typer(help="Some help.")` +* Explicitly set on `app.add_typer(sub_app, help="Some help.")` + +And the priority to set the command's **name**, from lowest priority to highest, is: -* Implicitly inferred from `sub_app = typer.Typer(callback=some_function)` (only the help text) -* Implicitly inferred from the callback function under `@sub_app.callback()` (only the help text) -* Implicitly inferred from `app.add_typer(sub_app, callback=some_function)` (only the help text) -* Explicitly set on `sub_app = typer.Typer(name="some-name", help="Some help.")` -* Explicitly set on `app.add_typer(sub_app, name="some-name", help="Some help.")` +* Explicitly set on `sub_app = typer.Typer(name="some-name")` +* Explicitly set on `app.add_typer(sub_app, name="some-name")` So, `app.add_typer(sub_app, name="some-name", help="Some help.")` always wins. diff --git a/docs_src/subcommands/name_help/tutorial007.py b/docs_src/subcommands/name_help/tutorial007.py index fcac500ab1..aaf7aec9fc 100644 --- a/docs_src/subcommands/name_help/tutorial007.py +++ b/docs_src/subcommands/name_help/tutorial007.py @@ -9,7 +9,7 @@ def old_callback(): """ -users_app = typer.Typer(callback=old_callback, name="exp-users", help="Explicit help.") +users_app = typer.Typer(callback=old_callback, name="users", help="Explicit help.") def new_users(): @@ -18,7 +18,7 @@ def new_users(): """ -app.add_typer(users_app, callback=new_users, name="users") +app.add_typer(users_app, callback=new_users) @users_app.callback(help="Help from callback for users.")