Adding upstream version 3.0.43.upstream/3.0.43

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

12 files changed, 831 insertions, 0 deletions

diff --git a/examples/prompts/auto-completion/autocomplete-with-control-space.py b/examples/prompts/auto-completion/autocomplete-with-control-space.py
new file mode 100755
index 0000000..61160a3
--- /dev/null
+++ b/examples/prompts/auto-completion/autocomplete-with-control-space.py
@@ -0,0 +1,75 @@
+#!/usr/bin/env python
+"""
+Example of using the control-space key binding for auto completion.
+"""
+from prompt_toolkit import prompt
+from prompt_toolkit.completion import WordCompleter
+from prompt_toolkit.key_binding import KeyBindings
+
+animal_completer = WordCompleter(
+    [
+        "alligator",
+        "ant",
+        "ape",
+        "bat",
+        "bear",
+        "beaver",
+        "bee",
+        "bison",
+        "butterfly",
+        "cat",
+        "chicken",
+        "crocodile",
+        "dinosaur",
+        "dog",
+        "dolphin",
+        "dove",
+        "duck",
+        "eagle",
+        "elephant",
+        "fish",
+        "goat",
+        "gorilla",
+        "kangaroo",
+        "leopard",
+        "lion",
+        "mouse",
+        "rabbit",
+        "rat",
+        "snake",
+        "spider",
+        "turkey",
+        "turtle",
+    ],
+    ignore_case=True,
+)
+
+
+kb = KeyBindings()
+
+
+@kb.add("c-space")
+def _(event):
+    """
+    Start auto completion. If the menu is showing already, select the next
+    completion.
+    """
+    b = event.app.current_buffer
+    if b.complete_state:
+        b.complete_next()
+    else:
+        b.start_completion(select_first=False)
+
+
+def main():
+    text = prompt(
+        "Give some animals: ",
+        completer=animal_completer,
+        complete_while_typing=False,
+        key_bindings=kb,
+    )
+    print("You said: %s" % text)
+
+
+if __name__ == "__main__":
+    main()
diff --git a/examples/prompts/auto-completion/autocompletion-like-readline.py b/examples/prompts/auto-completion/autocompletion-like-readline.py
new file mode 100755
index 0000000..613d3e7
--- /dev/null
+++ b/examples/prompts/auto-completion/autocompletion-like-readline.py
@@ -0,0 +1,58 @@
+#!/usr/bin/env python
+"""
+Autocompletion example that displays the autocompletions like readline does by
+binding a custom handler to the Tab key.
+"""
+from prompt_toolkit.completion import WordCompleter
+from prompt_toolkit.shortcuts import CompleteStyle, prompt
+
+animal_completer = WordCompleter(
+    [
+        "alligator",
+        "ant",
+        "ape",
+        "bat",
+        "bear",
+        "beaver",
+        "bee",
+        "bison",
+        "butterfly",
+        "cat",
+        "chicken",
+        "crocodile",
+        "dinosaur",
+        "dog",
+        "dolphin",
+        "dove",
+        "duck",
+        "eagle",
+        "elephant",
+        "fish",
+        "goat",
+        "gorilla",
+        "kangaroo",
+        "leopard",
+        "lion",
+        "mouse",
+        "rabbit",
+        "rat",
+        "snake",
+        "spider",
+        "turkey",
+        "turtle",
+    ],
+    ignore_case=True,
+)
+
+
+def main():
+    text = prompt(
+        "Give some animals: ",
+        completer=animal_completer,
+        complete_style=CompleteStyle.READLINE_LIKE,
+    )
+    print("You said: %s" % text)
+
+
+if __name__ == "__main__":
+    main()
diff --git a/examples/prompts/auto-completion/autocompletion.py b/examples/prompts/auto-completion/autocompletion.py
new file mode 100755
index 0000000..fc9dda0
--- /dev/null
+++ b/examples/prompts/auto-completion/autocompletion.py
@@ -0,0 +1,60 @@
+#!/usr/bin/env python
+"""
+Autocompletion example.
+
+Press [Tab] to complete the current word.
+- The first Tab press fills in the common part of all completions
+    and shows all the completions. (In the menu)
+- Any following tab press cycles through all the possible completions.
+"""
+from prompt_toolkit import prompt
+from prompt_toolkit.completion import WordCompleter
+
+animal_completer = WordCompleter(
+    [
+        "alligator",
+        "ant",
+        "ape",
+        "bat",
+        "bear",
+        "beaver",
+        "bee",
+        "bison",
+        "butterfly",
+        "cat",
+        "chicken",
+        "crocodile",
+        "dinosaur",
+        "dog",
+        "dolphin",
+        "dove",
+        "duck",
+        "eagle",
+        "elephant",
+        "fish",
+        "goat",
+        "gorilla",
+        "kangaroo",
+        "leopard",
+        "lion",
+        "mouse",
+        "rabbit",
+        "rat",
+        "snake",
+        "spider",
+        "turkey",
+        "turtle",
+    ],
+    ignore_case=True,
+)
+
+
+def main():
+    text = prompt(
+        "Give some animals: ", completer=animal_completer, complete_while_typing=False
+    )
+    print("You said: %s" % text)
+
+
+if __name__ == "__main__":
+    main()
diff --git a/examples/prompts/auto-completion/colored-completions-with-formatted-text.py b/examples/prompts/auto-completion/colored-completions-with-formatted-text.py
new file mode 100755
index 0000000..8a89c7a
--- /dev/null
+++ b/examples/prompts/auto-completion/colored-completions-with-formatted-text.py
@@ -0,0 +1,137 @@
+#!/usr/bin/env python
+"""
+Demonstration of a custom completer class and the possibility of styling
+completions independently by passing formatted text objects to the "display"
+and "display_meta" arguments of "Completion".
+"""
+from prompt_toolkit.completion import Completer, Completion
+from prompt_toolkit.formatted_text import HTML
+from prompt_toolkit.shortcuts import CompleteStyle, prompt
+
+animals = [
+    "alligator",
+    "ant",
+    "ape",
+    "bat",
+    "bear",
+    "beaver",
+    "bee",
+    "bison",
+    "butterfly",
+    "cat",
+    "chicken",
+    "crocodile",
+    "dinosaur",
+    "dog",
+    "dolphin",
+    "dove",
+    "duck",
+    "eagle",
+    "elephant",
+]
+
+animal_family = {
+    "alligator": "reptile",
+    "ant": "insect",
+    "ape": "mammal",
+    "bat": "mammal",
+    "bear": "mammal",
+    "beaver": "mammal",
+    "bee": "insect",
+    "bison": "mammal",
+    "butterfly": "insect",
+    "cat": "mammal",
+    "chicken": "bird",
+    "crocodile": "reptile",
+    "dinosaur": "reptile",
+    "dog": "mammal",
+    "dolphin": "mammal",
+    "dove": "bird",
+    "duck": "bird",
+    "eagle": "bird",
+    "elephant": "mammal",
+}
+
+family_colors = {
+    "mammal": "ansimagenta",
+    "insect": "ansigreen",
+    "reptile": "ansired",
+    "bird": "ansiyellow",
+}
+
+meta = {
+    "alligator": HTML(
+        "An <ansired>alligator</ansired> is a <u>crocodilian</u> in the genus Alligator of the family Alligatoridae."
+    ),
+    "ant": HTML(
+        "<ansired>Ants</ansired> are eusocial <u>insects</u> of the family Formicidae."
+    ),
+    "ape": HTML(
+        "<ansired>Apes</ansired> (Hominoidea) are a branch of Old World tailless anthropoid catarrhine <u>primates</u>."
+    ),
+    "bat": HTML("<ansired>Bats</ansired> are mammals of the order <u>Chiroptera</u>."),
+    "bee": HTML(
+        "<ansired>Bees</ansired> are flying <u>insects</u> closely related to wasps and ants."
+    ),
+    "beaver": HTML(
+        "The <ansired>beaver</ansired> (genus Castor) is a large, primarily <u>nocturnal</u>, semiaquatic <u>rodent</u>."
+    ),
+    "bear": HTML(
+        "<ansired>Bears</ansired> are carnivoran <u>mammals</u> of the family Ursidae."
+    ),
+    "butterfly": HTML(
+        "<ansiblue>Butterflies</ansiblue> are <u>insects</u> in the macrolepidopteran clade Rhopalocera from the order Lepidoptera."
+    ),
+    # ...
+}
+
+
+class AnimalCompleter(Completer):
+    def get_completions(self, document, complete_event):
+        word = document.get_word_before_cursor()
+        for animal in animals:
+            if animal.startswith(word):
+                if animal in animal_family:
+                    family = animal_family[animal]
+                    family_color = family_colors.get(family, "default")
+
+                    display = HTML(
+                        "%s<b>:</b> <ansired>(<"
+                        + family_color
+                        + ">%s</"
+                        + family_color
+                        + ">)</ansired>"
+                    ) % (animal, family)
+                else:
+                    display = animal
+
+                yield Completion(
+                    animal,
+                    start_position=-len(word),
+                    display=display,
+                    display_meta=meta.get(animal),
+                )
+
+
+def main():
+    # Simple completion menu.
+    print("(The completion menu displays colors.)")
+    prompt("Type an animal: ", completer=AnimalCompleter())
+
+    # Multi-column menu.
+    prompt(
+        "Type an animal: ",
+        completer=AnimalCompleter(),
+        complete_style=CompleteStyle.MULTI_COLUMN,
+    )
+
+    # Readline-like
+    prompt(
+        "Type an animal: ",
+        completer=AnimalCompleter(),
+        complete_style=CompleteStyle.READLINE_LIKE,
+    )
+
+
+if __name__ == "__main__":
+    main()
diff --git a/examples/prompts/auto-completion/colored-completions.py b/examples/prompts/auto-completion/colored-completions.py
new file mode 100755
index 0000000..9c5cba3
--- /dev/null
+++ b/examples/prompts/auto-completion/colored-completions.py
@@ -0,0 +1,78 @@
+#!/usr/bin/env python
+"""
+Demonstration of a custom completer class and the possibility of styling
+completions independently.
+"""
+from prompt_toolkit.completion import Completer, Completion
+from prompt_toolkit.output.color_depth import ColorDepth
+from prompt_toolkit.shortcuts import CompleteStyle, prompt
+
+colors = [
+    "red",
+    "blue",
+    "green",
+    "orange",
+    "purple",
+    "yellow",
+    "cyan",
+    "magenta",
+    "pink",
+]
+
+
+class ColorCompleter(Completer):
+    def get_completions(self, document, complete_event):
+        word = document.get_word_before_cursor()
+        for color in colors:
+            if color.startswith(word):
+                yield Completion(
+                    color,
+                    start_position=-len(word),
+                    style="fg:" + color,
+                    selected_style="fg:white bg:" + color,
+                )
+
+
+def main():
+    # Simple completion menu.
+    print("(The completion menu displays colors.)")
+    prompt("Type a color: ", completer=ColorCompleter())
+
+    # Multi-column menu.
+    prompt(
+        "Type a color: ",
+        completer=ColorCompleter(),
+        complete_style=CompleteStyle.MULTI_COLUMN,
+    )
+
+    # Readline-like
+    prompt(
+        "Type a color: ",
+        completer=ColorCompleter(),
+        complete_style=CompleteStyle.READLINE_LIKE,
+    )
+
+    # Prompt with true color output.
+    message = [
+        ("#cc2244", "T"),
+        ("#bb4444", "r"),
+        ("#996644", "u"),
+        ("#cc8844", "e "),
+        ("#ccaa44", "C"),
+        ("#bbaa44", "o"),
+        ("#99aa44", "l"),
+        ("#778844", "o"),
+        ("#55aa44", "r "),
+        ("#33aa44", "p"),
+        ("#11aa44", "r"),
+        ("#11aa66", "o"),
+        ("#11aa88", "m"),
+        ("#11aaaa", "p"),
+        ("#11aacc", "t"),
+        ("#11aaee", ": "),
+    ]
+    prompt(message, completer=ColorCompleter(), color_depth=ColorDepth.TRUE_COLOR)
+
+
+if __name__ == "__main__":
+    main()
diff --git a/examples/prompts/auto-completion/combine-multiple-completers.py b/examples/prompts/auto-completion/combine-multiple-completers.py
new file mode 100755
index 0000000..511988b
--- /dev/null
+++ b/examples/prompts/auto-completion/combine-multiple-completers.py
@@ -0,0 +1,76 @@
+#!/usr/bin/env python
+"""
+Example of multiple individual completers that are combined into one.
+"""
+from prompt_toolkit import prompt
+from prompt_toolkit.completion import WordCompleter, merge_completers
+
+animal_completer = WordCompleter(
+    [
+        "alligator",
+        "ant",
+        "ape",
+        "bat",
+        "bear",
+        "beaver",
+        "bee",
+        "bison",
+        "butterfly",
+        "cat",
+        "chicken",
+        "crocodile",
+        "dinosaur",
+        "dog",
+        "dolphin",
+        "dove",
+        "duck",
+        "eagle",
+        "elephant",
+        "fish",
+        "goat",
+        "gorilla",
+        "kangaroo",
+        "leopard",
+        "lion",
+        "mouse",
+        "rabbit",
+        "rat",
+        "snake",
+        "spider",
+        "turkey",
+        "turtle",
+    ],
+    ignore_case=True,
+)
+
+color_completer = WordCompleter(
+    [
+        "red",
+        "green",
+        "blue",
+        "yellow",
+        "white",
+        "black",
+        "orange",
+        "gray",
+        "pink",
+        "purple",
+        "cyan",
+        "magenta",
+        "violet",
+    ],
+    ignore_case=True,
+)
+
+
+def main():
+    completer = merge_completers([animal_completer, color_completer])
+
+    text = prompt(
+        "Give some animals: ", completer=completer, complete_while_typing=False
+    )
+    print("You said: %s" % text)
+
+
+if __name__ == "__main__":
+    main()
diff --git a/examples/prompts/auto-completion/fuzzy-custom-completer.py b/examples/prompts/auto-completion/fuzzy-custom-completer.py
new file mode 100755
index 0000000..fd9a7d7
--- /dev/null
+++ b/examples/prompts/auto-completion/fuzzy-custom-completer.py
@@ -0,0 +1,56 @@
+#!/usr/bin/env python
+"""
+Demonstration of a custom completer wrapped in a `FuzzyCompleter` for fuzzy
+matching.
+"""
+from prompt_toolkit.completion import Completer, Completion, FuzzyCompleter
+from prompt_toolkit.shortcuts import CompleteStyle, prompt
+
+colors = [
+    "red",
+    "blue",
+    "green",
+    "orange",
+    "purple",
+    "yellow",
+    "cyan",
+    "magenta",
+    "pink",
+]
+
+
+class ColorCompleter(Completer):
+    def get_completions(self, document, complete_event):
+        word = document.get_word_before_cursor()
+        for color in colors:
+            if color.startswith(word):
+                yield Completion(
+                    color,
+                    start_position=-len(word),
+                    style="fg:" + color,
+                    selected_style="fg:white bg:" + color,
+                )
+
+
+def main():
+    # Simple completion menu.
+    print("(The completion menu displays colors.)")
+    prompt("Type a color: ", completer=FuzzyCompleter(ColorCompleter()))
+
+    # Multi-column menu.
+    prompt(
+        "Type a color: ",
+        completer=FuzzyCompleter(ColorCompleter()),
+        complete_style=CompleteStyle.MULTI_COLUMN,
+    )
+
+    # Readline-like
+    prompt(
+        "Type a color: ",
+        completer=FuzzyCompleter(ColorCompleter()),
+        complete_style=CompleteStyle.READLINE_LIKE,
+    )
+
+
+if __name__ == "__main__":
+    main()
diff --git a/examples/prompts/auto-completion/fuzzy-word-completer.py b/examples/prompts/auto-completion/fuzzy-word-completer.py
new file mode 100755
index 0000000..329c0c1
--- /dev/null
+++ b/examples/prompts/auto-completion/fuzzy-word-completer.py
@@ -0,0 +1,59 @@
+#!/usr/bin/env python
+"""
+Autocompletion example.
+
+Press [Tab] to complete the current word.
+- The first Tab press fills in the common part of all completions
+    and shows all the completions. (In the menu)
+- Any following tab press cycles through all the possible completions.
+"""
+from prompt_toolkit.completion import FuzzyWordCompleter
+from prompt_toolkit.shortcuts import prompt
+
+animal_completer = FuzzyWordCompleter(
+    [
+        "alligator",
+        "ant",
+        "ape",
+        "bat",
+        "bear",
+        "beaver",
+        "bee",
+        "bison",
+        "butterfly",
+        "cat",
+        "chicken",
+        "crocodile",
+        "dinosaur",
+        "dog",
+        "dolphin",
+        "dove",
+        "duck",
+        "eagle",
+        "elephant",
+        "fish",
+        "goat",
+        "gorilla",
+        "kangaroo",
+        "leopard",
+        "lion",
+        "mouse",
+        "rabbit",
+        "rat",
+        "snake",
+        "spider",
+        "turkey",
+        "turtle",
+    ]
+)
+
+
+def main():
+    text = prompt(
+        "Give some animals: ", completer=animal_completer, complete_while_typing=True
+    )
+    print("You said: %s" % text)
+
+
+if __name__ == "__main__":
+    main()
diff --git a/examples/prompts/auto-completion/multi-column-autocompletion-with-meta.py b/examples/prompts/auto-completion/multi-column-autocompletion-with-meta.py
new file mode 100755
index 0000000..5ba3ab5
--- /dev/null
+++ b/examples/prompts/auto-completion/multi-column-autocompletion-with-meta.py
@@ -0,0 +1,50 @@
+#!/usr/bin/env python
+"""
+Autocompletion example that shows meta-information alongside the completions.
+"""
+from prompt_toolkit.completion import WordCompleter
+from prompt_toolkit.shortcuts import CompleteStyle, prompt
+
+animal_completer = WordCompleter(
+    [
+        "alligator",
+        "ant",
+        "ape",
+        "bat",
+        "bear",
+        "beaver",
+        "bee",
+        "bison",
+        "butterfly",
+        "cat",
+        "chicken",
+        "crocodile",
+        "dinosaur",
+        "dog",
+        "dolphin",
+        "dove",
+        "duck",
+        "eagle",
+        "elephant",
+    ],
+    meta_dict={
+        "alligator": "An alligator is a crocodilian in the genus Alligator of the family Alligatoridae.",
+        "ant": "Ants are eusocial insects of the family Formicidae",
+        "ape": "Apes (Hominoidea) are a branch of Old World tailless anthropoid catarrhine primates ",
+        "bat": "Bats are mammals of the order Chiroptera",
+    },
+    ignore_case=True,
+)
+
+
+def main():
+    text = prompt(
+        "Give some animals: ",
+        completer=animal_completer,
+        complete_style=CompleteStyle.MULTI_COLUMN,
+    )
+    print("You said: %s" % text)
+
+
+if __name__ == "__main__":
+    main()
diff --git a/examples/prompts/auto-completion/multi-column-autocompletion.py b/examples/prompts/auto-completion/multi-column-autocompletion.py
new file mode 100755
index 0000000..7fcfc52
--- /dev/null
+++ b/examples/prompts/auto-completion/multi-column-autocompletion.py
@@ -0,0 +1,57 @@
+#!/usr/bin/env python
+"""
+Similar to the autocompletion example. But display all the completions in multiple columns.
+"""
+from prompt_toolkit.completion import WordCompleter
+from prompt_toolkit.shortcuts import CompleteStyle, prompt
+
+animal_completer = WordCompleter(
+    [
+        "alligator",
+        "ant",
+        "ape",
+        "bat",
+        "bear",
+        "beaver",
+        "bee",
+        "bison",
+        "butterfly",
+        "cat",
+        "chicken",
+        "crocodile",
+        "dinosaur",
+        "dog",
+        "dolphin",
+        "dove",
+        "duck",
+        "eagle",
+        "elephant",
+        "fish",
+        "goat",
+        "gorilla",
+        "kangaroo",
+        "leopard",
+        "lion",
+        "mouse",
+        "rabbit",
+        "rat",
+        "snake",
+        "spider",
+        "turkey",
+        "turtle",
+    ],
+    ignore_case=True,
+)
+
+
+def main():
+    text = prompt(
+        "Give some animals: ",
+        completer=animal_completer,
+        complete_style=CompleteStyle.MULTI_COLUMN,
+    )
+    print("You said: %s" % text)
+
+
+if __name__ == "__main__":
+    main()
diff --git a/examples/prompts/auto-completion/nested-autocompletion.py b/examples/prompts/auto-completion/nested-autocompletion.py
new file mode 100755
index 0000000..cd85b8c
--- /dev/null
+++ b/examples/prompts/auto-completion/nested-autocompletion.py
@@ -0,0 +1,22 @@
+#!/usr/bin/env python
+"""
+Example of nested autocompletion.
+"""
+from prompt_toolkit import prompt
+from prompt_toolkit.completion import NestedCompleter
+
+completer = NestedCompleter.from_nested_dict(
+    {
+        "show": {"version": None, "clock": None, "ip": {"interface": {"brief": None}}},
+        "exit": None,
+    }
+)
+
+
+def main():
+    text = prompt("Type a command: ", completer=completer)
+    print("You said: %s" % text)
+
+
+if __name__ == "__main__":
+    main()
diff --git a/examples/prompts/auto-completion/slow-completions.py b/examples/prompts/auto-completion/slow-completions.py
new file mode 100755
index 0000000..cce9d59
--- /dev/null
+++ b/examples/prompts/auto-completion/slow-completions.py
@@ -0,0 +1,103 @@
+#!/usr/bin/env python
+"""
+An example of how to deal with slow auto completion code.
+
+- Running the completions in a thread is possible by wrapping the
+  `Completer` object in a `ThreadedCompleter`. This makes sure that the
+  ``get_completions`` generator is executed in a background thread.
+
+  For the `prompt` shortcut, we don't have to wrap the completer ourselves.
+  Passing `complete_in_thread=True` is sufficient.
+
+- We also set a `loading` boolean in the completer function to keep track of
+  when the completer is running, and display this in the toolbar.
+"""
+import time
+
+from prompt_toolkit.completion import Completer, Completion
+from prompt_toolkit.shortcuts import CompleteStyle, prompt
+
+WORDS = [
+    "alligator",
+    "ant",
+    "ape",
+    "bat",
+    "bear",
+    "beaver",
+    "bee",
+    "bison",
+    "butterfly",
+    "cat",
+    "chicken",
+    "crocodile",
+    "dinosaur",
+    "dog",
+    "dolphin",
+    "dove",
+    "duck",
+    "eagle",
+    "elephant",
+    "fish",
+    "goat",
+    "gorilla",
+    "kangaroo",
+    "leopard",
+    "lion",
+    "mouse",
+    "rabbit",
+    "rat",
+    "snake",
+    "spider",
+    "turkey",
+    "turtle",
+]
+
+
+class SlowCompleter(Completer):
+    """
+    This is a completer that's very slow.
+    """
+
+    def __init__(self):
+        self.loading = 0
+
+    def get_completions(self, document, complete_event):
+        # Keep count of how many completion generators are running.
+        self.loading += 1
+        word_before_cursor = document.get_word_before_cursor()
+
+        try:
+            for word in WORDS:
+                if word.startswith(word_before_cursor):
+                    time.sleep(0.2)  # Simulate slowness.
+                    yield Completion(word, -len(word_before_cursor))
+
+        finally:
+            # We use try/finally because this generator can be closed if the
+            # input text changes before all completions are generated.
+            self.loading -= 1
+
+
+def main():
+    # We wrap it in a ThreadedCompleter, to make sure it runs in a different
+    # thread. That way, we don't block the UI while running the completions.
+    slow_completer = SlowCompleter()
+
+    # Add a bottom toolbar that display when completions are loading.
+    def bottom_toolbar():
+        return " Loading completions... " if slow_completer.loading > 0 else ""
+
+    # Display prompt.
+    text = prompt(
+        "Give some animals: ",
+        completer=slow_completer,
+        complete_in_thread=True,
+        complete_while_typing=True,
+        bottom_toolbar=bottom_toolbar,
+        complete_style=CompleteStyle.MULTI_COLUMN,
+    )
+    print("You said: %s" % text)
+
+
+if __name__ == "__main__":
+    main()