rename to "choice".

Author: jonathanslenders

docs/pages/choice_prompts.rst

@@ -5,14 +5,14 @@ Asking for a choice
 
 Similar to how the :func:`~prompt_toolkit.shortcuts.prompt` function allows for
 text input, prompt_toolkit has a
-:func:`~prompt_toolkit.shortcuts.prompt_choice` function to ask for a choice
+:func:`~prompt_toolkit.shortcuts.choice` function to ask for a choice
 from a list of options:
 
 .. code:: python
 
-    from prompt_toolkit.shortcuts import prompt_choice
+    from prompt_toolkit.shortcuts import choice
 
-    result = prompt_choice(
+    result = choice(
         message="Please choose a dish",
         options=[
             ("pizza", "Pizza with mushrooms"),
@@ -40,7 +40,7 @@ styles. The ``message`` parameter takes any :ref:`formatted text
     from __future__ import annotations
 
     from prompt_toolkit.formatted_text import HTML
-    from prompt_toolkit.shortcuts import prompt_choice
+    from prompt_toolkit.shortcuts import choice
     from prompt_toolkit.styles import Style
 
     style = Style.from_dict(
@@ -52,7 +52,7 @@ styles. The ``message`` parameter takes any :ref:`formatted text
         }
     )
 
-    result = prompt_choice(
+    result = choice(
         message=HTML("<u>Please select a dish</u>:"),
         options=[
             ("pizza", "Pizza with mushrooms"),
@@ -70,15 +70,15 @@ styles. The ``message`` parameter takes any :ref:`formatted text
 Adding a frame
 --------------
 
-The :func:`~prompt_toolkit.shortcuts.prompt_choice` function takes a
+The :func:`~prompt_toolkit.shortcuts.choice` function takes a
 ``show_frame`` argument. When set to ``True``, the options will be shown
 inside a frame. It is also possible to pass a :ref:`filter <filters>`, like
 ``~is_done``, so that the frame is only displayed when asking for input, but
 hidden once the input is accepted.
 
 .. code:: python
 
-    from prompt_toolkit.shortcuts import prompt_choice
+    from prompt_toolkit.shortcuts import choice
     from prompt_toolkit.filters import is_done
     from prompt_toolkit.styles import Style
 
@@ -88,7 +88,7 @@ hidden once the input is accepted.
             "selected-option": "bold underline",
         }
     )
-    result = prompt_choice(
+    result = choice(
         message="Please select a dish:",
         options=[
             ("pizza", "Pizza with mushrooms"),

examples/choice-prompts/color.py renamed to examples/choices/color.py

@@ -1,7 +1,7 @@
 from __future__ import annotations
 
 from prompt_toolkit.formatted_text import HTML
-from prompt_toolkit.shortcuts import prompt_choice
+from prompt_toolkit.shortcuts import choice
 from prompt_toolkit.styles import Style
 
 
@@ -15,7 +15,7 @@ def main() -> None:
         }
     )
 
-    result = prompt_choice(
+    result = choice(
         message=HTML("<u>Please select a dish</u>:"),
         options=[
             ("pizza", "Pizza with mushrooms"),

examples/choice-prompts/default.py renamed to examples/choices/default.py

@@ -1,11 +1,11 @@
 from __future__ import annotations
 
 from prompt_toolkit.formatted_text import HTML
-from prompt_toolkit.shortcuts import prompt_choice
+from prompt_toolkit.shortcuts import choice
 
 
 def main() -> None:
-    result = prompt_choice(
+    result = choice(
         message=HTML("<u>Please select a dish</u>:"),
         options=[
             ("pizza", "Pizza with mushrooms"),

examples/choice-prompts/gray-frame-on-accept.py renamed to examples/choices/gray-frame-on-accept.py

@@ -1,7 +1,7 @@
 from __future__ import annotations
 
 from prompt_toolkit.formatted_text import HTML
-from prompt_toolkit.shortcuts import prompt_choice
+from prompt_toolkit.shortcuts import choice
 from prompt_toolkit.styles import Style
 
 
@@ -14,7 +14,7 @@ def main() -> None:
         }
     )
 
-    result = prompt_choice(
+    result = choice(
         message=HTML("<u>Please select a dish</u>:"),
         options=[
             ("pizza", "Pizza with mushrooms"),

examples/choice-prompts/many-options.py renamed to examples/choices/many-choices.py

@@ -1,10 +1,10 @@
 from __future__ import annotations
 
-from prompt_toolkit.shortcuts import prompt_choice
+from prompt_toolkit.shortcuts import choice
 
 
 def main() -> None:
-    result = prompt_choice(
+    result = choice(
         message="Please select an option:",
         options=[(i, f"Option {i}") for i in range(1, 100)],
     )

examples/choice-prompts/mouse-support.py renamed to examples/choices/mouse-support.py

@@ -1,11 +1,11 @@
 from __future__ import annotations
 
 from prompt_toolkit.formatted_text import HTML
-from prompt_toolkit.shortcuts import prompt_choice
+from prompt_toolkit.shortcuts import choice
 
 
 def main() -> None:
-    result = prompt_choice(
+    result = choice(
         message=HTML("<u>Please select a dish</u>:"),
         options=[
             ("pizza", "Pizza with mushrooms"),

examples/choice-prompts/simple-selection.py renamed to examples/choices/simple-selection.py

@@ -1,10 +1,10 @@
 from __future__ import annotations
 
-from prompt_toolkit.shortcuts import prompt_choice
+from prompt_toolkit.shortcuts import choice
 
 
 def main() -> None:
-    result = prompt_choice(
+    result = choice(
         message="Please select a dish:",
         options=[
             ("pizza", "Pizza with mushrooms"),

examples/choice-prompts/with-frame.py renamed to examples/choices/with-frame.py

@@ -2,7 +2,7 @@
 
 from prompt_toolkit.filters import is_done
 from prompt_toolkit.formatted_text import HTML
-from prompt_toolkit.shortcuts import prompt_choice
+from prompt_toolkit.shortcuts import choice
 from prompt_toolkit.styles import Style
 
 
@@ -14,7 +14,7 @@ def main() -> None:
         }
     )
 
-    result = prompt_choice(
+    result = choice(
         message=HTML("<u>Please select a dish</u>:"),
         options=[
             ("pizza", "Pizza with mushrooms"),

src/prompt_toolkit/__init__.py

@@ -26,7 +26,7 @@
 )
 from .application import Application
 from .formatted_text import ANSI, HTML
-from .shortcuts import PromptSession, print_formatted_text, prompt
+from .shortcuts import PromptSession, choice, print_formatted_text, prompt
 
 # Don't forget to update in `docs/conf.py`!
 __version__ = metadata.version("prompt_toolkit")
@@ -42,6 +42,7 @@
     "Application",
     # Shortcuts.
     "prompt",
+    "choice",
     "PromptSession",
     "print_formatted_text",
     # Formatted text.

src/prompt_toolkit/shortcuts/__init__.py

@@ -1,6 +1,6 @@
 from __future__ import annotations
 
-from .choice import prompt_choice
+from .choice_input import choice
 from .dialogs import (
     button_dialog,
     checkboxlist_dialog,
@@ -39,7 +39,7 @@
     "ProgressBar",
     "ProgressBarCounter",
     # Choice selection.
-    "prompt_choice",
+    "choice",
     # Utils.
     "clear",
     "clear_title",