pyFlowLauncher

https://garulf.github.io/pyFlowLauncher/
Admin
pyFlowLauncher is a Python API for quickly creating plugins for Flow Launcher with support for...
Tokens:10,520
Snippets:103
Trust Score:9.7
Update:5 months ago
Show doc for...
Tokens:
Raw
### Install pyFlowLauncher

Source: https://garulf.github.io/pyFlowLauncher

Install the pyFlowLauncher package using pip. Use the `[all]` flag for compatibility with Python versions older than 3.11.

```bash
python -m pip install pyflowlauncher[all]
```

--------------------------------

### Start Loading Bar

Source: https://garulf.github.io/pyFlowLauncher/reference/api

Initiates the display of a loading bar in Flow Launcher. This is typically used to indicate that a long-running operation is in progress.

```python
def start_loading_bar() -> JsonRPCAction:
    """Start the loading bar in Flow Launcher."""
    return _send_action("StartLoadingBar")
```

--------------------------------

### Reload Plugins

Source: https://garulf.github.io/pyFlowLauncher/reference/api

Reloads all installed plugins in Flow Launcher. This is useful after making changes to plugin code or configuration.

```python
def reload_plugins() -> JsonRPCAction:
    """Reload the plugins in Flow Launcher."""
    return _send_action("ReloadPlugins")
```

--------------------------------

### Register Methods with @plugin.on_method Decorator

Source: https://garulf.github.io/pyFlowLauncher/guide/Plugin%20methods

Use the @plugin.on_method decorator to register functions as callable methods within your plugin. This example shows how to register both a query method and an action method.

```python
from pyflowlauncher import Plugin, Result, send_results
from pyflowlauncher.result import ResultResponse

plugin = Plugin()


@plugin.on_method
def query(query: str) -> ResultResponse:
    r = Result(
        Title="This is a title!",
        SubTitle="This is the subtitle!",
        JsonRPCAction={"method": "action", "parameters": []}
    )
    return send_results([r])


@plugin.on_method
def action(params: list[str]):
    pass
    # Do stuff here
    # ...


plugin.run()

```

--------------------------------

### Get Event from EventHandler

Source: https://garulf.github.io/pyFlowLauncher/reference/event

Retrieves an event callable by its registered name. Raises EventNotFound if the event is not found.

```python
def get_event(self, event: str) -> Callable[..., Any]:
    try:
        return self._events[event]
    except KeyError:
        raise EventNotFound(event)
```

--------------------------------

### change_query

Source: https://garulf.github.io/pyFlowLauncher/reference/api

Changes the current query displayed in Flow Launcher. This can be used to dynamically update search results or guide the user.

```APIDOC
## change_query

### Description
Change the query in Flow Launcher.

### Method
`change_query(query: str, requery: bool = False)`

### Parameters
- **query** (str) - The new query string to set.
- **requery** (bool, optional) - Whether to trigger a re-query. Defaults to False.

### Response
Returns a `JsonRPCAction` object.
```

--------------------------------

### reload_plugins

Source: https://garulf.github.io/pyFlowLauncher/reference/api

Reloads all installed plugins within the Flow Launcher application. This is useful after making changes to plugin configurations or code.

```APIDOC
## reload_plugins

### Description
Reload the plugins in Flow Launcher.

### Method
`reload_plugins()`

### Response
Returns a `JsonRPCAction` object.
```

--------------------------------

### Plugin Initialization

Source: https://garulf.github.io/pyFlowLauncher/reference/plugin

Initializes the Plugin class, setting up internal components like logger, client, and event handler. Optionally adds provided methods.

```python
def __init__(self, methods: list[Method] | None = None) -> None:
    self._logger = logger(self)
    self._client = JsonRPCClient()
    self._event_handler = EventHandler()
    self._settings: dict[str, Any] = {}
    if methods:
        self.add_methods(methods)

```

--------------------------------

### run

Source: https://garulf.github.io/pyFlowLauncher/reference/plugin

Executes the plugin by receiving a request, triggering the appropriate event handler, and sending back feedback.

```APIDOC
## run

### Description
Executes the plugin by receiving a request, triggering the appropriate event handler, and sending back feedback.

### Method Signature
`run() -> None`

### Behavior
1. Receives a request from the client.
2. Extracts the method and parameters from the request.
3. Triggers the corresponding event handler using `_event_handler.trigger_event`.
4. Handles differences in asyncio event loop management based on Python version.
5. If feedback is generated, sends it back to the client.
6. Returns early if no feedback is produced.
```

--------------------------------

### Create Basic pyFlowLauncher Plugin

Source: https://garulf.github.io/pyFlowLauncher

A basic plugin structure using a function as the query method. Ensure to import necessary classes from `pyflowlauncher`.

```python
from pyflowlauncher import Plugin, Result, send_results
from pyflowlauncher.result import ResultResponse

plugin = Plugin()


@plugin.on_method
def query(query: str) -> ResultResponse:
    r = Result(
        Title="This is a title!",
        SubTitle="This is the subtitle!",
        IcoPath="icon.png"
    )
    return send_results([r])


plugin.run()
```

--------------------------------

### show_app

Source: https://garulf.github.io/pyFlowLauncher/reference/api

Brings the Flow Launcher application window to the foreground, making it visible and active.

```APIDOC
## show_app

### Description
Show Flow Launcher.

### Method
`show_app()`

### Response
Returns a `JsonRPCAction` object.
```

--------------------------------

### Retrieve Plugin Manifest

Source: https://garulf.github.io/pyFlowLauncher/reference/plugin

Loads and returns the plugin's manifest file, which contains metadata about the plugin.

```python
def manifest(self) -> PluginManifestSchema:
    """Return the plugin manifest."""
    with open(self.root_dir() / MANIFEST_FILE, 'r', encoding='utf-8') as f:
        manifest = json.load(f)
    return manifest
```

--------------------------------

### Define PreviewInfo for Flow Launcher

Source: https://garulf.github.io/pyFlowLauncher/reference/result

Use this TypedDict to define preview information for a Flow Launcher result. It can include an image path, a description, media status, and a preview delegate.

```python
class PreviewInfo(TypedDict):
    """Flow Launcher Preview section"""
    PreviewImagePath: Optional[str]
    Description: Optional[str]
    IsMedia: bool
    PreviewDeligate: Optional[str]
```

--------------------------------

### start_loading_bar

Source: https://garulf.github.io/pyFlowLauncher/reference/api

Initiates the display of a loading bar within the Flow Launcher interface, typically used to indicate ongoing background processes.

```APIDOC
## start_loading_bar

### Description
Start the loading bar in Flow Launcher.

### Method
`start_loading_bar()`

### Response
Returns a `JsonRPCAction` object.
```

--------------------------------

### manifest

Source: https://garulf.github.io/pyFlowLauncher/reference/plugin

Retrieves and returns the plugin's manifest information.

```APIDOC
## manifest

### Description
Return the plugin manifest.

### Method Signature
`manifest() -> PluginManifestSchema`

### Returns
- **PluginManifestSchema**: An object containing the plugin's manifest details.
```

--------------------------------

### Show Flow Launcher

Source: https://garulf.github.io/pyFlowLauncher/reference/api

Brings the Flow Launcher application window to the foreground, making it visible to the user.

```python
def show_app() -> JsonRPCAction:
    """Show Flow Launcher."""
    return _send_action("ShowApp")
```

--------------------------------

### Create Advanced pyFlowLauncher Plugin

Source: https://garulf.github.io/pyFlowLauncher

An advanced plugin structure using a `Method` class for the query method. This allows for more complex plugin logic.

```python
from pyflowlauncher import Plugin, Result, Method
from pyflowlauncher.result import ResultResponse

plugin = Plugin()


class Query(Method):

    def __call__(self, query: str) -> ResultResponse:
        r = Result(
            Title="This is a title!",
            SubTitle="This is the subtitle!"
        )
        self.add_result(r)
        return self.return_results()

plugin.add_method(Query())
plugin.run()
```

--------------------------------

### Initialize EventHandler

Source: https://garulf.github.io/pyFlowLauncher/reference/event

Initializes an EventHandler instance, setting up internal dictionaries for events and handlers.

```python
def __init__(self):
    self._events = {}
    self._handlers = {}
```

--------------------------------

### Initialize EventNotFound Exception

Source: https://garulf.github.io/pyFlowLauncher/reference/event

Initializes the EventNotFound exception with the name of the event that was not found.

```python
def __init__(self, event: str):
    self.event = event
    super().__init__(f"Event '{event}' not found.")
```

--------------------------------

### Open Settings Dialog

Source: https://garulf.github.io/pyFlowLauncher/reference/api

Opens the Flow Launcher settings window. This allows users to configure application preferences.

```python
def open_setting_dialog() -> JsonRPCAction:
    """Open the settings window in Flow Launcher."""
    return _send_action("OpenSettingDialog")
```

--------------------------------

### Score Search Results with PyFlowLauncher

Source: https://garulf.github.io/pyFlowLauncher/guide/scoring_results

Use this snippet to generate and score search results. It initializes a plugin, defines a query method that creates 100 dummy results, and then uses `score_results` to rank them based on the user's input before sending them.

```python
from pyflowlauncher import Plugin, Result, send_results
from pyflowlauncher.result import ResultResponse
from pyflowlauncher.utils import score_results

plugin = Plugin()


@plugin.on_method
def query(query: str) -> ResultResponse:
    results = []
    for _ in range(100):
        r = Result(
            Title="This is a title!",
            SubTitle="This is the subtitle!",
        )
        results.append(r)
    return send_results(score_results(query, results))


plugin.run()

```

--------------------------------

### open_setting_dialog

Source: https://garulf.github.io/pyFlowLauncher/reference/api

Opens the settings window of the Flow Launcher application, allowing users to configure its behavior.

```APIDOC
## open_setting_dialog

### Description
Open the settings window in Flow Launcher.

### Method
`open_setting_dialog()`

### Response
Returns a `JsonRPCAction` object.
```

--------------------------------

### Import and Use Built-in Admin Icon

Source: https://garulf.github.io/pyFlowLauncher/guide/Launcher_Icons

Demonstrates importing the ADMIN icon from the pyflowlauncher.icons module and assigning it to the IcoPath of a Result object. Ensure PyFlowLauncher can locate the Flow Launcher directory for icons to load correctly.

```python
from pyflowlauncher import Plugin, Result, send_results
from pyflowlauncher.result import ResultResponse
from pyflowlauncher.icons import ADMIN

plugin = Plugin()


@plugin.on_method
def query(query: str) -> ResultResponse:
    r = Result(
        Title="This is a title!",
        SubTitle="This is the subtitle!",
        IcoPath=ADMIN
    )
    return send_results([r])


plugin.run()
```

--------------------------------

### shell_run

Source: https://garulf.github.io/pyFlowLauncher/reference/api

Executes a command in the system's shell. By default, it uses `cmd.exe` but can be configured to use other shells.

```APIDOC
## shell_run

### Description
Run a shell command.

### Method
`shell_run(command: str, filename: str = 'cmd.exe')`

### Parameters
- **command** (str) - The shell command to execute.
- **filename** (str, optional) - The shell executable to use. Defaults to 'cmd.exe'.

### Response
Returns a `JsonRPCAction` object.
```

--------------------------------

### method

Source: https://garulf.github.io/pyFlowLauncher/reference/plugin

Registers a method to be executed when the plugin is invoked.

```APIDOC
## method

### Description
Register a method to be called when the plugin is run.

### Method Signature
`method(method: Method) -> Method`

### Parameters
- **method** (Method): The method to register.

### Returns
- **Method**: The registered method.
```

--------------------------------

### Open Directory

Source: https://garulf.github.io/pyFlowLauncher/reference/api

Opens a specified directory in the file explorer. An optional filename or filepath can be provided to highlight a specific item within the directory.

```python
def open_directory(directory_path: str, filename_or_filepath: Optional[str] = None) -> JsonRPCAction:
    """Open a directory."""
    return _send_action("OpenDirectory", directory_path, filename_or_filepath)
```

--------------------------------

### Register and Add Method to Result in One Line

Source: https://garulf.github.io/pyFlowLauncher/guide/Plugin%20methods

Register a method and add it to a Result in a single step using the plugin.action method. This is useful for directly associating an action with a search result.

```python
from pyflowlauncher import Plugin, Result, send_results
from pyflowlauncher.result import ResultResponse

plugin = Plugin()


@plugin.on_method
def query(query: str) -> ResultResponse:
    r = Result(
        Title="This is a title!",
        SubTitle="This is the subtitle!",
        JsonRPCAction=plugin.action(action, ["stuff"])
    )
    return send_results([r])


def action(params: list[str]):
    pass
    # Do stuff here
    # ...


plugin.run()

```

--------------------------------

### Send API Request from a Custom Method

Source: https://garulf.github.io/pyFlowLauncher/guide/API%20Requests

This demonstrates how to send an API request, like changing the query, from a custom method within your plugin. This approach allows for more complex interactions triggered by user actions.

```python
from pyflowlauncher import Plugin, Result, send_results, api
from pyflowlauncher.result import JsonRPCAction, ResultResponse

plugin = Plugin()


@plugin.on_method
def example_method() -> JsonRPCAction:
    # Do stuff here
    return api.change_query("This is also a new query!")


@plugin.on_method
def query(query: str) -> ResultResponse:
    r = Result(
        Title="This is a title!",
        SubTitle="This is the subtitle!",
        IcoPath="icon.png",
    )
    r.add_action(example_method)
    return send_results([r])


plugin.run()
```

--------------------------------

### Define Namespace

Source: https://garulf.github.io/pyFlowLauncher/reference/api

Defines the namespace for Flow Launcher.

```python
NAME_SPACE = 'Flow.Launcher'
```

--------------------------------

### open_directory

Source: https://garulf.github.io/pyFlowLauncher/reference/api

Opens a specified directory in the file explorer. An optional filename or filepath can be provided to select a specific item within the directory.

```APIDOC
## open_directory

### Description
Open a directory.

### Method
`open_directory(directory_path: str, filename_or_filepath: Optional[str] = None)`

### Parameters
- **directory_path** (str) - The path to the directory to open.
- **filename_or_filepath** (Optional[str], optional) - The name or full path of a file within the directory to select. Defaults to None.

### Response
Returns a `JsonRPCAction` object.
```

--------------------------------

### open_uri

Source: https://garulf.github.io/pyFlowLauncher/reference/api

Opens a Uniform Resource Identifier (URI) using the system's default handler for that URI scheme.

```APIDOC
## open_uri

### Description
Open a URI.

### Method
`open_uri(uri: str)`

### Parameters
- **uri** (str) - The URI to open.

### Response
Returns a `JsonRPCAction` object.
```

--------------------------------

### show_msg

Source: https://garulf.github.io/pyFlowLauncher/reference/api

Displays a message dialog within Flow Launcher with a specified title, subtitle, and an optional icon path.

```APIDOC
## show_msg

### Description
Show a message in Flow Launcher.

### Method
`show_msg(title: str, sub_title: str, ico_path: str = '')`

### Parameters
- **title** (str) - The main title of the message dialog.
- **sub_title** (str) - The subtitle or main content of the message.
- **ico_path** (str, optional) - The file path to an icon to display. Defaults to an empty string.

### Response
Returns a `JsonRPCAction` object.
```

--------------------------------

### Run Shell Command

Source: https://garulf.github.io/pyFlowLauncher/reference/api

Executes a command in the system's shell. By default, it uses `cmd.exe`. This is useful for running system utilities or scripts.

```python
def shell_run(command: str, filename: str = 'cmd.exe') -> JsonRPCAction:
    """Run a shell command."""
    return _send_action("ShellRun", command, filename)
```

--------------------------------

### Execute Plugin Method Based on Request

Source: https://garulf.github.io/pyFlowLauncher/reference/plugin

Handles incoming requests, determines the method to execute, and dispatches the event. It manages event loop execution based on Python version.

```python
def run(self) -> None:
    request = self._client.recieve()
    method = request["method"]
    parameters = request.get('parameters', [])
    if sys.version_info >= (3, 10, 0):
        feedback = asyncio.run(self._event_handler.trigger_event(method, *parameters))
    else:
        loop = asyncio.get_event_loop()
        feedback = loop.run_until_complete(self._event_handler.trigger_event(method, *parameters))
    if not feedback:
        return
    self._client.send(feedback)
```

--------------------------------

### Determine Plugin Root Directory

Source: https://garulf.github.io/pyFlowLauncher/reference/plugin

Locates the plugin's root directory by searching for the manifest file in the current directory and its parents. Raises `FileNotFoundError` if not found.

```python
def root_dir(self) -> Path:
    """Return the root directory of the plugin."""
    current_dir = self.run_dir
    for part in current_dir.parts:
        if current_dir.joinpath(MANIFEST_FILE).exists():
            return current_dir
        current_dir = current_dir.parent
    raise FileNotFoundError(f"Could not find {MANIFEST_FILE} in {self.run_dir} or any parent directory.")
```

--------------------------------

### Show Message

Source: https://garulf.github.io/pyFlowLauncher/reference/api

Displays a message dialog to the user within Flow Launcher. It includes a title, subtitle, and an optional icon path.

```python
def show_msg(title: str, sub_title: str, ico_path: str = "") -> JsonRPCAction:
    """Show a message in Flow Launcher."""
    return _send_action("ShowMsg", title, sub_title, ico_path)
```

--------------------------------

### root_dir

Source: https://garulf.github.io/pyFlowLauncher/reference/plugin

Determines and returns the root directory of the plugin by searching for the manifest file.

```APIDOC
## root_dir

### Description
Return the root directory of the plugin.

### Method Signature
`root_dir() -> Path`

### Returns
- **Path**: The path object representing the plugin's root directory.

### Raises
- **FileNotFoundError**: If the manifest file cannot be found in the current or parent directories.
```

--------------------------------

### Plugin Class Definition

Source: https://garulf.github.io/pyFlowLauncher/reference/plugin

Defines the core Plugin class for pyflowlauncher, including initialization, method registration, exception handling, and execution logic.

```python
class Plugin:

    def __init__(self, methods: list[Method] | None = None) -> None:
        self._logger = logger(self)
        self._client = JsonRPCClient()
        self._event_handler = EventHandler()
        self._settings: dict[str, Any] = {}
        if methods:
            self.add_methods(methods)

    def add_method(self, method: Method) -> str:
        """Add a method to the event handler."""
        return self._event_handler.add_event(method)

    def add_methods(self, methods: Iterable[Method]) -> None:
        self._event_handler.add_events(methods)

    def on_method(self, method: Method) -> Method:
        @wraps(method)
        def wrapper(*args, **kwargs):
            return method(*args, **kwargs)
        self._event_handler.add_event(wrapper)
        return wrapper

    def method(self, method: Method) -> Method:
        """Register a method to be called when the plugin is run."""
        return self.on_method(method)

    def add_exception_handler(self, exception: Type[Exception], handler: Callable[..., Any]) -> None:
        """Add exception handler to be called when an exception is raised in a method."""
        self._event_handler.add_exception_handler(exception, handler)

    def on_except(self, exception: Type[Exception]) -> Callable[..., Any]:
        @wraps(exception)
        def wrapper(handler: Callable[..., Any]) -> Callable[..., Any]:
            self.add_exception_handler(exception, handler)
            return handler
        return wrapper

    def action(self, method: Method, parameters: Optional[Iterable] = None) -> JsonRPCAction:
        """Register a method and return a JsonRPCAction that calls it."""
        method_name = self.add_method(method)
        return {"method": method_name, "parameters": parameters or []}

    @property
    def settings(self) -> dict:
        if self._settings is None:
            self._settings = {}
        self._settings = self._client.recieve().get('settings', {})
        return self._settings

    def run(self) -> None:
        request = self._client.recieve()
        method = request["method"]
        parameters = request.get('parameters', [])
        if sys.version_info >= (3, 10, 0):
            feedback = asyncio.run(self._event_handler.trigger_event(method, *parameters))
        else:
            loop = asyncio.get_event_loop()
            feedback = loop.run_until_complete(self._event_handler.trigger_event(method, *parameters))
        if not feedback:
            return
        self._client.send(feedback)

    @property
    def run_dir(self) -> Path:
        """Return the run directory of the plugin."""
        return Path(sys.argv[0]).parent

    def root_dir(self) -> Path:
        """Return the root directory of the plugin."""
        current_dir = self.run_dir
        for part in current_dir.parts:
            if current_dir.joinpath(MANIFEST_FILE).exists():
                return current_dir
            current_dir = current_dir.parent
        raise FileNotFoundError(f"Could not find {MANIFEST_FILE} in {self.run_dir} or any parent directory.")

    def manifest(self) -> PluginManifestSchema:
        """Return the plugin manifest."""
        with open(self.root_dir() / MANIFEST_FILE, 'r', encoding='utf-8') as f:
            manifest = json.load(f)
        return manifest

```

--------------------------------

### Create a Flow Launcher Result

Source: https://garulf.github.io/pyFlowLauncher/reference/result

Use the Result dataclass to construct a result object for Flow Launcher. It includes fields for title, subtitle, icon, score, actions, context data, glyph, copy text, autocomplete text, and preview information.

```python
@dataclass
class Result:
    Title: str
    SubTitle: Optional[str] = None
    IcoPath: Optional[Union[str, Path]] = None
    Score: int = 0
    JsonRPCAction: Optional[JsonRPCAction] = None
    ContextData: Optional[Iterable] = None
    Glyph: Optional[Glyph] = None
    CopyText: Optional[str] = None
    AutoCompleteText: Optional[str] = None
    RoundedIcon: bool = False
    Preview: Optional[PreviewInfo] = None

    def as_dict(self) -> Dict[str, Any]:
        return self.__dict__

    def add_action(self, method: Method, 
                   parameters: Optional[Iterable[Any]] = None, 
                   *, 
                   dont_hide_after_action: bool = False) -> None:
        self.JsonRPCAction = {
            "method": method.__name__,
            "parameters": parameters or [],
            "dontHideAfterAction": dont_hide_after_action
        }
```

--------------------------------

### on_method

Source: https://garulf.github.io/pyFlowLauncher/reference/plugin

Registers a method to be called when the plugin is run, wrapping it for event handling.

```APIDOC
## on_method

### Description
Registers a method to be called when the plugin is run, wrapping it for event handling.

### Method Signature
`on_method(method: Method) -> Method`

### Parameters
- **method** (Method): The method to register.

### Returns
- **Method**: The wrapped method ready for event handling.
```

--------------------------------

### add_methods

Source: https://garulf.github.io/pyFlowLauncher/reference/plugin

Adds multiple methods to the event handler.

```APIDOC
## add_methods

### Description
Adds multiple methods to the event handler.

### Method Signature
`add_methods(methods: Iterable[Method]) -> None`

### Parameters
- **methods** (Iterable[Method]): An iterable of methods to add to the event handler.
```

--------------------------------

### open_url

Source: https://garulf.github.io/pyFlowLauncher/reference/api

Opens a given URL in the default web browser. It supports opening URLs in a private browsing mode.

```APIDOC
## open_url

### Description
Open a URL.

### Method
`open_url(url: str, in_private: bool = False)`

### Parameters
- **url** (str) - The URL to open.
- **in_private** (bool, optional) - If True, opens the URL in a private browsing session. Defaults to False.

### Response
Returns a `JsonRPCAction` object.
```

--------------------------------

### Change Query from a Result

Source: https://garulf.github.io/pyFlowLauncher/guide/API%20Requests

Use this when you want to change the Flow Launcher query after a user selects a result. Ensure you are not using this within a query or context_menu method.

```python
from pyflowlauncher import Plugin, Result, send_results, api
from pyflowlauncher.result import ResultResponse

plugin = Plugin()


@plugin.on_method
def query(query: str) -> ResultResponse:
    r = Result(
        Title="This is a title!",
        SubTitle="This is the subtitle!",
        IcoPath="icon.png",
        JsonRPCAction=api.change_query("This is a new query!"),
    )
    return send_results([r])


plugin.run()
```

--------------------------------

### copy_to_clipboard

Source: https://garulf.github.io/pyFlowLauncher/reference/api

Copies the provided text to the system clipboard. Optionally, it can bypass the default notification.

```APIDOC
## copy_to_clipboard

### Description
Copy text to the clipboard.

### Method
`copy_to_clipboard(text: str, direct_copy: bool = False, show_default_notification=True)`

### Parameters
- **text** (str) - The text to copy to the clipboard.
- **direct_copy** (bool, optional) - If True, bypasses default notification. Defaults to False.
- **show_default_notification** (bool, optional) - Whether to show the default notification. Defaults to True.

### Response
Returns a `JsonRPCAction` object.
```

--------------------------------

### Copy Text to Clipboard

Source: https://garulf.github.io/pyFlowLauncher/reference/api

Copies the provided text to the system clipboard. Optionally, a direct copy can be performed without showing a default notification.

```python
def copy_to_clipboard(text: str, direct_copy: bool = False, show_default_notification=True) -> JsonRPCAction:
    """Copy text to the clipboard."""
    return _send_action("CopyToClipboard", text, direct_copy, show_default_notification)
```

--------------------------------

### Open URL

Source: https://garulf.github.io/pyFlowLauncher/reference/api

Opens a given URL in the default web browser. The `in_private` parameter allows opening the URL in a private browsing session.

```python
def open_url(url: str, in_private: bool = False) -> JsonRPCAction:
    """Open a URL."""
    return _send_action("OpenUrl", url, in_private)
```

--------------------------------

### Open URI

Source: https://garulf.github.io/pyFlowLauncher/reference/api

Opens a Uniform Resource Identifier (URI). This can be used for various protocols like `mailto:` or custom application URIs.

```python
def open_uri(uri: str) -> JsonRPCAction:
    """Open a URI."""
    return _send_action("OpenAppUri", uri)
```

--------------------------------

### Plugin Class Methods

Source: https://garulf.github.io/pyFlowLauncher/reference/plugin

Methods available on the Plugin class.

```APIDOC
## Plugin Methods

### `__init__`

*   **Signature**: `__init__(methods: list[Method] | None = None) -> None`
*   **Description**: Initializes a new instance of the Plugin class. It sets up logging, a JSON-RPC client, an event handler, and optionally adds initial methods.

### `action`

*   **Signature**: `action(method: Method, parameters: Optional[Iterable] = None) -> JsonRPCAction`
*   **Description**: Registers a method to be called and returns a `JsonRPCAction` that can invoke it. This is useful for defining actions that can be triggered by the system.

### `add_exception_handler`

*   **Signature**: `add_exception_handler(exception: Type[Exception], handler: Callable[..., Any]) -> None`
*   **Description**: Adds a custom handler to manage specific exceptions raised within plugin methods.

### `add_method`

*   **Signature**: `add_method(method: Method) -> str`
*   **Description**: Adds a single method to the plugin's event handler, returning the registered method name.

### `add_methods`

*   **Signature**: `add_methods(methods: Iterable[Method]) -> None`
*   **Description**: Adds multiple methods to the plugin's event handler.

### `manifest`

*   **Signature**: `manifest() -> PluginManifestSchema`
*   **Description**: Reads and returns the plugin's manifest file, providing metadata about the plugin.

### `method`

*   **Signature**: `method(method: Method) -> Method`
*   **Description**: Decorator to register a method to be called when the plugin is executed.

### `on_except`

*   **Signature**: `on_except(exception: Type[Exception]) -> Callable[..., Any]`
*   **Description**: Decorator to register an exception handler for a specific exception type.

### `on_method`

*   **Signature**: `on_method(method: Method) -> Method`
*   **Description**: Decorator that registers a method to be called when the plugin is run, similar to the `method` decorator.

### `run`

*   **Signature**: `run() -> None`
*   **Description**: Executes the plugin by receiving a request, triggering the appropriate event handler, and sending back the feedback. Handles asynchronous operations based on Python version.

### `root_dir`

*   **Signature**: `root_dir() -> Path`
*   **Description**: Determines and returns the root directory of the plugin by searching for the manifest file in parent directories.
```

--------------------------------

### PreviewInfo TypedDict

Source: https://garulf.github.io/pyFlowLauncher/reference/result

Contains information for the preview pane of a search result.

```APIDOC
## class PreviewInfo(TypedDict)

Contains preview information for a result.

### Attributes
- **PreviewImagePath** (Optional[str]) - Path to the preview image.
- **Description** (Optional[str]) - Description text for the preview.
- **IsMedia** (bool) - Indicates if the preview is media.
- **PreviewDeligate** (Optional[str]) - Delegate for handling the preview.
```

--------------------------------

### Register Method for Plugin Execution

Source: https://garulf.github.io/pyFlowLauncher/reference/plugin

Registers a method to be executed when the plugin is invoked. This is a convenience wrapper around `on_method`.

```python
def method(self, method: Method) -> Method:
    """Register a method to be called when the plugin is run."""
    return self.on_method(method)
```

--------------------------------

### Plugin Class Properties

Source: https://garulf.github.io/pyFlowLauncher/reference/plugin

Properties available on the Plugin class.

```APIDOC
## Plugin Properties

### `run_dir`

*   **Type**: `Path`
*   **Description**: Returns the run directory of the plugin.

### `settings`

*   **Type**: `dict`
*   **Description**: Retrieves and returns the plugin's settings.
```

--------------------------------

### send_results

Source: https://garulf.github.io/pyFlowLauncher/reference/result

Formats and returns results as a JsonRPCResponse. It takes an iterable of Result objects and an optional dictionary of settings, returning a ResultResponse.

```APIDOC
## send_results

### Description
Formats and returns results as a JsonRPCResponse.

### Method Signature
`send_results(results: Iterable[Result], settings: Optional[Dict[str, Any]] = None) -> ResultResponse`

### Parameters
- **results** (Iterable[Result]): An iterable collection of Result objects to be formatted.
- **settings** (Optional[Dict[str, Any]]): An optional dictionary containing settings. Defaults to None.

### Returns
- **ResultResponse**: A dictionary representing the JsonRPCResponse, containing the formatted results and any provided settings.
```

--------------------------------

### add_method

Source: https://garulf.github.io/pyFlowLauncher/reference/plugin

Adds a single method to the event handler, making it available for execution.

```APIDOC
## add_method

### Description
Add a method to the event handler.

### Method Signature
`add_method(method: Method) -> str`

### Parameters
- **method** (Method): The method to add to the event handler.

### Returns
- **str**: An identifier for the added method.
```

--------------------------------

### Define Flow Launcher Glyph

Source: https://garulf.github.io/pyFlowLauncher/reference/result

Use this TypedDict to define the glyph information for a Flow Launcher result. It includes the glyph string and its associated font family.

```python
class Glyph(TypedDict):
    """Flow Launcher Glyph"""
    Glyph: str
    FontFamily: str
```

--------------------------------

### on_except

Source: https://garulf.github.io/pyFlowLauncher/reference/plugin

Decorator to register an exception handler for a specific exception type.

```APIDOC
## on_except

### Description
Decorator to register an exception handler for a specific exception type.

### Method Signature
`on_except(exception: Type[Exception]) -> Callable[..., Any]`

### Parameters
- **exception** (Type[Exception]): The type of exception to associate the handler with.

### Returns
- **Callable[..., Any]**: A decorator that registers the handler function.
```

--------------------------------

### Change Query in Flow Launcher

Source: https://garulf.github.io/pyFlowLauncher/reference/api

Changes the current query displayed in Flow Launcher. Use this to dynamically update search results or prompts.

```python
def change_query(query: str, requery: bool = False) -> JsonRPCAction:
    """Change the query in Flow Launcher."""
    return _send_action("ChangeQuery", query, requery)
```

--------------------------------

### Register Action Method

Source: https://garulf.github.io/pyFlowLauncher/reference/plugin

Registers a method to be called as an action and returns a JsonRPCAction object. Useful for defining callable plugin actions.

```python
def action(self, method: Method, parameters: Optional[Iterable] = None) -> JsonRPCAction:
    """Register a method and return a JsonRPCAction that calls it."""
    method_name = self.add_method(method)
    return {"method": method_name, "parameters": parameters or []}

```

--------------------------------

### Add Multiple Methods to Plugin

Source: https://garulf.github.io/pyFlowLauncher/reference/plugin

Adds multiple methods to the plugin's event handler efficiently.

```python
def add_methods(self, methods: Iterable[Method]) -> None:
    self._event_handler.add_events(methods)
```

--------------------------------

### Format and Send Results as JsonRPCResponse

Source: https://garulf.github.io/pyFlowLauncher/reference/result

Use this function to format a list of results into a JsonRPCResponse. It accepts an iterable of Result objects and optional settings.

```python
def send_results(results: Iterable[Result], settings: Optional[Dict[str, Any]] = None) -> ResultResponse:
    """Formats and returns results as a JsonRPCResponse"""
    return {'result': [result.as_dict() for result in results], 'SettingsChange': settings}
```

--------------------------------

### Decorator for Exception Handling

Source: https://garulf.github.io/pyFlowLauncher/reference/plugin

Provides a decorator to easily attach exception handlers to methods. It wraps the handler and registers it.

```python
def on_except(self, exception: Type[Exception]) -> Callable[..., Any]:
    @wraps(exception)
    def wrapper(handler: Callable[..., Any]) -> Callable[..., Any]:
        self.add_exception_handler(exception, handler)
        return handler
    return wrapper
```

--------------------------------

### Hide Flow Launcher

Source: https://garulf.github.io/pyFlowLauncher/reference/api

Hides the Flow Launcher application window. The application remains running in the background.

```python
def hide_app() -> JsonRPCAction:
    """Hide Flow Launcher."""
    return _send_action("HideApp")
```

--------------------------------

### stop_loading_bar

Source: https://garulf.github.io/pyFlowLauncher/reference/api

Hides or stops the loading bar in the Flow Launcher interface, signaling the completion of a process.

```APIDOC
## stop_loading_bar

### Description
Stop the loading bar in Flow Launcher.

### Method
`stop_loading_bar()`

### Response
Returns a `JsonRPCAction` object.
```

--------------------------------

### Define ResultResponse Structure

Source: https://garulf.github.io/pyFlowLauncher/reference/result

Use this TypedDict to define the structure of a ResultResponse from Flow Launcher. It contains a list of result dictionaries and an optional setting change dictionary.

```python
class ResultResponse(TypedDict):
    result: List[Dict[str, Any]]
    SettingsChange: NotRequired[Optional[Dict[str, Any]]]
```

--------------------------------

### hide_app

Source: https://garulf.github.io/pyFlowLauncher/reference/api

Hides the Flow Launcher application window. This is useful for scenarios where the launcher should be temporarily out of sight.

```APIDOC
## hide_app

### Description
Hide Flow Launcher.

### Method
`hide_app()`

### Response
Returns a `JsonRPCAction` object.
```

--------------------------------

### Stop Loading Bar

Source: https://garulf.github.io/pyFlowLauncher/reference/api

Hides the loading bar in Flow Launcher. Call this after a process that was indicated by the loading bar has completed.

```python
def stop_loading_bar() -> JsonRPCAction:
    """Stop the loading bar in Flow Launcher."""
    return _send_action("StopLoadingBar")
```

--------------------------------

### close_app

Source: https://garulf.github.io/pyFlowLauncher/reference/api

Closes the Flow Launcher application. This is a utility function to terminate the application.

```APIDOC
## close_app

### Description
Close Flow Launcher.

### Method
`close_app()`

### Response
Returns a `JsonRPCAction` object.
```

--------------------------------

### Define JsonRPCAction for Flow Launcher

Source: https://garulf.github.io/pyFlowLauncher/reference/result

Use this TypedDict to define a JsonRPCAction for a Flow Launcher result. It specifies the method to call, its parameters, and an option to prevent hiding the action after execution.

```python
class JsonRPCAction(TypedDict):
    """Flow Launcher JsonRPCAction"""
    method: str
    parameters: Iterable
    dontHideAfterAction: NotRequired[bool]
```

--------------------------------

### Result Class

Source: https://garulf.github.io/pyFlowLauncher/reference/result

Represents a single search result item. It includes properties for title, subtitle, icon, score, actions, context, glyph, copy text, autocomplete text, and preview information.

```APIDOC
## class Result

Represents a single search result item.

### Attributes
- **Title** (str) - The main title of the result.
- **SubTitle** (Optional[str]) - An optional subtitle for the result.
- **IcoPath** (Optional[Union[str, Path]]) - Path to the icon for the result.
- **Score** (int) - The score of the result, used for ranking.
- **JsonRPCAction** (Optional[JsonRPCAction]) - Defines an action to be performed when the result is selected.
- **ContextData** (Optional[Iterable]) - Additional data associated with the result context.
- **Glyph** (Optional[Glyph]) - Glyph information for the result.
- **CopyText** (Optional[str]) - Text to be copied to the clipboard when the result is activated.
- **AutoCompleteText** (Optional[str]) - Text to be used for auto-completion.
- **RoundedIcon** (bool) - Whether the icon should be rounded.
- **Preview** (Optional[PreviewInfo]) - Information for the preview pane.

### Methods
#### as_dict()
Converts the Result object into a dictionary.

#### add_action(method: Method, parameters: Optional[Iterable[Any]] = None, *, dont_hide_after_action: bool = False) -> None
Adds a JsonRPCAction to the result.
```

--------------------------------

### Convert Result to Dictionary

Source: https://garulf.github.io/pyFlowLauncher/reference/result

The `as_dict` method converts a Result object into a dictionary representation, which is useful for serialization or further processing.

```python
def as_dict(self) -> Dict[str, Any]:
    return self.__dict__
```

--------------------------------

### EventNotFound Exception

Source: https://garulf.github.io/pyFlowLauncher/reference/event

Custom exception raised when an event is requested but not found in the handler.

```APIDOC
## Exception: EventNotFound

### Description
Raised when an event with a specified name is not found within the `EventHandler`.

### Attributes

#### `event` (str)
Stores the name of the event that was not found.
```

--------------------------------

### EventNotFound Exception Definition

Source: https://garulf.github.io/pyFlowLauncher/reference/event

Custom exception raised when an event is requested but not found in the EventHandler's registry.

```python
class EventNotFound(Exception):

    def __init__(self, event: str):
        self.event = event
        super().__init__(f"Event '{event}' not found.")
```

--------------------------------

### ResultResponse TypedDict

Source: https://garulf.github.io/pyFlowLauncher/reference/result

Represents the structure of a response containing search results and optional settings changes.

```APIDOC
## class ResultResponse(TypedDict)

Represents the response structure for search results.

### Attributes
- **result** (List[Dict[str, Any]]) - A list of result dictionaries.
- **SettingsChange** (NotRequired[Optional[Dict[str, Any]]]) - Optional dictionary for settings changes.
```

--------------------------------

### Add Exception Handler to Plugin

Source: https://garulf.github.io/pyFlowLauncher/reference/plugin

Registers a handler for specific exceptions raised within a plugin method. This allows for graceful error management.

```python
def add_exception_handler(self, exception: Type[Exception], handler: Callable[..., Any]) -> None:
    """Add exception handler to be called when an exception is raised in a method."""
    self._event_handler.add_exception_handler(exception, handler)
```

--------------------------------

### Add JsonRPCAction to Result

Source: https://garulf.github.io/pyFlowLauncher/reference/result

The `add_action` method simplifies adding a JsonRPCAction to a Result object. It takes the method, optional parameters, and a flag to control hiding the action.

```python
def add_action(self, method: Method,
               parameters: Optional[Iterable[Any]] = None,
               *,
               dont_hide_after_action: bool = False) -> None:
    self.JsonRPCAction = {
        "method": method.__name__,
        "parameters": parameters or [],
        "dontHideAfterAction": dont_hide_after_action
    }
```

--------------------------------

### Close Flow Launcher

Source: https://garulf.github.io/pyFlowLauncher/reference/api

Closes the Flow Launcher application. This action terminates the running instance.

```python
def close_app() -> JsonRPCAction:
    """Close Flow Launcher."""
    return _send_action("CloseApp")
```

--------------------------------

### EventHandler Class

Source: https://garulf.github.io/pyFlowLauncher/reference/event

The EventHandler class manages events and their corresponding handlers. It allows adding events by name or automatically inferring names, registering exception handlers, and triggering events with optional arguments.

```APIDOC
## Class: EventHandler

### Description
Manages events and their handlers. Allows adding events, registering exception handlers, and triggering events.

### Methods

#### `__init__()`
Initializes the EventHandler with empty dictionaries for events and handlers.

#### `add_event(event: Callable[..., Any], *, name=None) -> str`
Adds a single event to the handler. The event can be named explicitly or its name can be inferred from the callable.

- **event** (Callable[..., Any]) - The event to add.
- **name** (str, optional) - The name to associate with the event. Defaults to the event's inferred name.

Returns the key (name) under which the event was registered.

#### `add_events(events: Iterable[Callable[..., Any]])`
Adds multiple events to the handler from an iterable.

- **events** (Iterable[Callable[..., Any]]) - An iterable of events to add.

#### `add_exception_handler(exception: Type[Exception], handler: Callable[..., Any])`
Registers a handler for a specific exception type.

- **exception** (Type[Exception]) - The type of exception to handle.
- **handler** (Callable[..., Any]) - The handler function to be called when the exception occurs.

#### `get_event(event: str) -> Callable[..., Any]`
Retrieves an event by its registered name.

- **event** (str) - The name of the event to retrieve.

Returns the event callable. Raises `EventNotFound` if the event is not found.

#### `trigger_event(event: str, *args, **kwargs) -> Any`
Triggers a specified event with given arguments and keyword arguments. If an exception occurs during event execution, it attempts to trigger a registered exception handler.

- **event** (str) - The name of the event to trigger.
- **args** - Positional arguments to pass to the event.
- **kwargs** - Keyword arguments to pass to the event.

Returns the result of the event execution or the result of the exception handler.

#### `trigger_exception_handler(exception: Exception) -> Any`
Triggers the registered handler for the given exception.

- **exception** (Exception) - The exception that occurred.

Returns the result of the exception handler. Re-raises the exception if no handler is found.
```

--------------------------------

### Add Multiple Events to EventHandler

Source: https://garulf.github.io/pyFlowLauncher/reference/event

Adds multiple events to the EventHandler by iterating through an iterable of callables.

```python
def add_events(self, events: Iterable[Callable[..., Any]]):
    for event in events:
        self.add_event(event)
```

--------------------------------

### Add Event to EventHandler

Source: https://garulf.github.io/pyFlowLauncher/reference/event

Adds a single event to the EventHandler. An optional name can be provided; otherwise, the event's callable name is used as the key.

```python
def add_event(self, event: Callable[..., Any], *, name=None) -> str:
    key = name or self._get_callable_name(event)
    self._events[key] = event
    return key
```

--------------------------------

### JsonRPCAction TypedDict

Source: https://garulf.github.io/pyFlowLauncher/reference/result

Defines a JsonRPC action that can be associated with a search result.

```APIDOC
## class JsonRPCAction(TypedDict)

Defines a JsonRPC action.

### Attributes
- **method** (str) - The name of the method to call.
- **parameters** (Iterable) - Parameters for the method call.
- **dontHideAfterAction** (NotRequired[bool]) - Whether to hide the Flow Launcher after the action is performed.
```

--------------------------------

### Add Method to Plugin

Source: https://garulf.github.io/pyFlowLauncher/reference/plugin

Adds a single method to the plugin's event handler, making it callable.

```python
def add_method(self, method: Method) -> str:
    """Add a method to the event handler."""
    return self._event_handler.add_event(method)
```

--------------------------------

### EventHandler Class Definition

Source: https://garulf.github.io/pyFlowLauncher/reference/event

Defines the EventHandler class for managing events and their handlers. It includes methods for adding events, registering exception handlers, and triggering events.

```python
class EventHandler:

    def __init__(self):
        self._events = {}
        self._handlers = {}

    def _get_callable_name(self, method: Union[Callable[..., Any], Exception]):
        return getattr(method, '__name__', method.__class__.__name__).lower()

    def add_event(self, event: Callable[..., Any], *, name=None) -> str:
        key = name or self._get_callable_name(event)
        self._events[key] = event
        return key

    def add_events(self, events: Iterable[Callable[..., Any]]):
        for event in events:
            self.add_event(event)

    def add_exception_handler(self, exception: Type[Exception], handler: Callable[..., Any]):
        self._handlers[exception] = handler

    def get_event(self, event: str) -> Callable[..., Any]:
        try:
            return self._events[event]
        except KeyError:
            raise EventNotFound(event)

    async def _await_maybe(self, result: Any) -> Any:
        if asyncio.iscoroutine(result):
            return await result
        return result

    async def trigger_exception_handler(self, exception: Exception) -> Any:
        try:
            handler = self._handlers[exception.__class__]
            return await self._await_maybe(handler(exception))
        except KeyError:
            raise exception

    async def trigger_event(self, event: str, *args, **kwargs) -> Any:
        try:
            result = self.get_event(event)(*args, **kwargs)
            return await self._await_maybe(result)
        except Exception as e:
            return await self.trigger_exception_handler(e)
```

--------------------------------

### Glyph TypedDict

Source: https://garulf.github.io/pyFlowLauncher/reference/result

Represents glyph information for a result, including the glyph string and font family.

```APIDOC
## class Glyph(TypedDict)

Represents glyph information for a result.

### Attributes
- **Glyph** (str) - The glyph string.
- **FontFamily** (str) - The font family of the glyph.
```

--------------------------------

### Add Exception Handler

Source: https://garulf.github.io/pyFlowLauncher/reference/event

Registers a handler function for a specific exception type. This handler will be called when an exception of the specified type occurs during event triggering.

```python
def add_exception_handler(self, exception: Type[Exception], handler: Callable[..., Any]):
    self._handlers[exception] = handler
```

--------------------------------

### add_exception_handler

Source: https://garulf.github.io/pyFlowLauncher/reference/plugin

Adds an exception handler to be called when a specific exception is raised within a plugin method.

```APIDOC
## add_exception_handler

### Description
Add exception handler to be called when an exception is raised in a method.

### Method Signature
`add_exception_handler(exception: Type[Exception], handler: Callable[..., Any]) -> None`

### Parameters
- **exception** (Type[Exception]): The type of exception to handle.
- **handler** (Callable[..., Any]): The function to call when the exception is caught.
```

--------------------------------

### Decorator for Method Wrapping

Source: https://garulf.github.io/pyFlowLauncher/reference/plugin

Wraps a method to be called by the event handler. This decorator ensures the method is properly registered and can be invoked.

```python
def on_method(self, method: Method) -> Method:
    @wraps(method)
    def wrapper(*args, **kwargs):
        return method(*args, **kwargs)
    self._event_handler.add_event(wrapper)
    return wrapper
```

--------------------------------

### Trigger Event Asynchronously

Source: https://garulf.github.io/pyFlowLauncher/reference/event

Triggers a registered event by its name, passing any provided arguments. It handles both synchronous and asynchronous event callables and catches exceptions, forwarding them to the exception handler.

```python
async def trigger_event(self, event: str, *args, **kwargs) -> Any:
    try:
        result = self.get_event(event)(*args, **kwargs)
        return await self._await_maybe(result)
    except Exception as e:
        return await self.trigger_exception_handler(e)
```

--------------------------------

### Trigger Exception Handler Asynchronously

Source: https://garulf.github.io/pyFlowLauncher/reference/event

Calls the registered handler for a given exception. It supports asynchronous handlers and re-raises the exception if no handler is found.

```python
async def trigger_exception_handler(self, exception: Exception) -> Any:
    try:
        handler = self._handlers[exception.__class__]
        return await self._await_maybe(handler(exception))
    except KeyError:
        raise exception
```
Tokens:
Raw