example.py

import keypirinha as kp

class Example(kp.Plugin):
    def __init__(self):
        super().__init__()

    def on_catalog(self):
        self.set_catalog([
            self.create_item(
                category=kp.ItemCategory.KEYWORD,
                label="catalog item required",
                short_desc="I am not executable",
                target="item1",
                args_hint=kp.ItemArgsHint.REQUIRED,
                hit_hint=kp.ItemHitHint.IGNORE
            )
        ])

    def on_suggest(self, user_input, items_chain):
        if not items_chain:
            return

        if len(items_chain) == 1 and items_chain[0].target() == "item1":
            self.set_suggestions([
                self.create_item(
                    category=kp.ItemCategory.KEYWORD,
                    label="suggestion item required",
                    short_desc="why am I executable?",
                    target="item2",
                    args_hint=kp.ItemArgsHint.REQUIRED,
                    hit_hint=kp.ItemHitHint.IGNORE,
                    loop_on_suggest=True
                )
            ])
        elif len(items_chain) == 2 and items_chain[1].target() == "item2":
            self.set_suggestions([
                self.create_item(
                    category=kp.ItemCategory.KEYWORD,
                    label="suggestion item forbidden",
                    short_desc="I am executable",
                    target="item3",
                    args_hint=kp.ItemArgsHint.FORBIDDEN,
                    hit_hint=kp.ItemHitHint.IGNORE
                )
            ])

    def on_execute(self, item, action):
        self.info("on_execute:",item.label())