API Reference

The following section outlines the API of flogin.

Types

type flogin.Jsonable

This is a type used to represent anything json serializable.

It is literally defined as:

str | int | float | None | bool | list["Jsonable"] | dict[str, "Jsonable"]

Plugins

Attributes
Methods
class flogin.plugin.Plugin[SettingsT](**options)[source]

This class represents your plugin.

Parameters:

  • settings_no_update (Optional[bool]) – Whether or not to let flow update flogin’s version of the settings. This can be useful when using a custom settings menu. Defaults to False

  • ignore_cancellation_requests (Optional[bool]) – Whether or not to ignore cancellation requests sent from flow. Defaults to False

  • disable_log_override_files (Optional[bool]) – Whether or not to disable the log override files. Defaults to False. See Log Override Files for more information on this.

@event[source]

A decorator that registers an event to listen for. This decorator can be used with a plugin instance or as a classmethod.

All events must be a coroutine.

Changed in version 1.1.0: The decorator can now be used as a classmethod

Note

See the event reference to see what valid events there are.

Example

With a plugin instance:

from flogin.utils import print

@plugin.event
async def on_initialization():
    print('Ready!')

As a classmethod:

from flogin.utils import print

class MyPlugin(Plugin):
    @Plugin.event
    async def on_initialization(self):
        print('Ready!')
@search(condition=None, *, text=..., pattern=..., keyword=..., allowed_keywords=..., disallowed_keywords=...)[source]

A decorator that registers a search handler.

All search handlers must be a coroutine. See the search handler section for more information about using search handlers.

Changed in version 2.0.0: The search decorator can now be used as a classmethod

Note

This decorator can also be used as a classmethod

Parameters:

  • condition (Optional[condition]) – The condition to determine which queries this handler should run on. If given, this should be the only argument given.

  • text (Optional[str]) – A kwarg to quickly add a PlainTextCondition. If given, this should be the only argument given.

  • pattern (Optional[re.Pattern | str]) – A kwarg to quickly add a RegexCondition. If given, this should be the only argument given.

  • keyword (Optional[str]) – A kwarg to quickly set the condition to a KeywordCondition condition with the keyword kwarg being the only allowed keyword.

  • allowed_keywords (Optional[Iterable[str]]) – A kwarg to quickly set the condition to a KeywordCondition condition with the kwarg being the list of allowed keywords.

  • disallowed_keywords (Optional[Iterable[str]]) – A kwarg to quickly set the condition to a KeywordCondition condition with the kwarg being the list of disallowed keywords.

Example

With an instance:

@plugin.search()
async def example_search_handler(data: Query):
    return "This is a result!"

As a classmethod:

class MyPlugin(Plugin):
    @Plugin.search()
    async def example_search_handler(self, data: Query):
        return "This is a result!"
api

An easy way to acess Flow Launcher’s API

Type:

FlowLauncherAPI

check_for_log_override_files()[source]

None=No-Changes, True=In-Prod, False=In-Debug

fetch_flow_settings()[source]

Fetches flow’s settings from flow’s config file

Returns:

FlowSettings – A dataclass containing all of flow’s settings

flow_application_dir

flow’s application directory from environment variables.

Added in version 1.0.1.

Raises:

EnvNotSet – This is raised when the environment variable for this property is not set by flow or the plugin tester.

Type:

Path

flow_program_dir

flow’s application program from environment variables.

Added in version 1.0.1.

Raises:

EnvNotSet – This is raised when the environment variable for this property is not set by flow or the plugin tester.

Type:

Path

flow_version

the flow version from environment variables.

Added in version 1.0.1.

Raises:

EnvNotSet – This is raised when the environment variable for this property is not set by flow or the plugin tester.

Type:

str

property last_query

The last query request that flow sent. This is None if no query request has been sent yet.

Type:

Query | None

property metadata

Returns the plugin’s metadata.

Raises:

PluginNotInitialized – This gets raised if the plugin hasn’t been initialized yet

register_event(callback, name=None)[source]

Registers an event to listen for. See the event() decorator for another method of registering events.

All events must be a coroutine.

Note

See the event reference to see what valid events there are.

Parameters:

  • callback (coroutine) – The coroutine to be executed with the event

  • name (Optional[str]) – The name of the event to be registered. Defaults to the callback’s name.

register_search_handler(handler)[source]

Register a new search handler

See the search handler section for more information about using search handlers.

Parameters:

handler (SearchHandler) – The search handler to be registered

register_search_handlers(*handlers)[source]

Register new search handlers

See the search handler section for more information about using search handlers.

Parameters:

*handlers (list[SearchHandler]) – The search handlers to be registered

run(*, setup_default_log_handler=True)[source]

The default runner. This runs the start() coroutine, and setups up logging.

Parameters:

setup_default_log_handler (bool) – Whether to setup the default log handler or not, defaults to True.

settings

The plugin’s settings set by the user

Type:

Settings

await start()[source]

This function is a coroutine.

The default startup/setup method. This can be overriden for advanced startup behavior, but make sure to run await super().start() to actually start your plugin.

Models

Settings

class flogin.settings.Settings[source]

This class represents the settings that you user has chosen.

If a setting is not found, None is returned instead.

x['setting name']

Get a setting by key similiar to a dictionary

x['setting name', 'default']

Get a setting by key similiar to a dictionary, with a custom default.

x['setting name'] = "new value"

Change a settings value like a dictionary

x.setting_name

Get a setting by name like an attribute

x.setting_name = "new value"

Change a settings value like an attribute

Query

Attributes
Methods
class flogin.query.Query[ConditionDataT][source]

This class represents the query data sent from flow launcher

x == y

Compare the keywords, text, and is_query values of two query objects.

hash(x)

Gets the hash of the query’s raw text

raw_text

The raw and complete query, which includes the keyword

Type:

str:

is_requery

Whether the query is a requery or not

Type:

bool

text

The actual query, excluding any keywords

Type:

str

keyword

The keyword used to initiate the query

Type:

str

property condition_data

If used in a SearchHandler, this attribute will return any extra data that the condition gave.

Type:

Any | None

await update(*, text=..., keyword=..., requery=False)[source]

This function is a coroutine.

Applies updates to the query with flow, and to this object.

This method provides quick acess to flogin.flow.api.FlowLauncherAPI.change_query()

Parameters:

  • text (Optional[str | None]) –

    The text that will be used with the query.

    Changed in version 2.0.0: text can now be None, and is now optional

  • keyword (Optional[str | None]) – The keyword that will be used with the query. Defaults to the pre-existing value of Query.keyword. Set this to None or * for no keyword to be used.

  • requery (Optional[bool]) – Whether or not to re-send a query request in the event that the new query is the same as the current query. Defaults to False

Raises:

JsonRPCException – This is raised when an error happens with the JsonRPC pipe while attempting to call this API method.

Returns:

None

await update_results(results)[source]

This function is a coroutine.

Tells flow to change the results shown to the user, using the query from this query object.

This method provides quick acess to flogin.flow.api.FlowLauncherAPI.update_results(). Because of that, this method will only take affect if the user has not changed the query.

Parameters:

results (list[Result]) – The new results

Raises:

JsonRPCException – This is raised when an error happens with the JsonRPC pipe while attempting to call this API method.

Returns:

None

JSON RPC

Results

Attributes
Methods
class flogin.jsonrpc.results.Result[PluginT](title=None, sub=None, icon=None, title_highlight_data=None, title_tooltip=None, sub_tooltip=None, copy_text=None, score=None, auto_complete_text=None, preview=None, progress_bar=None, rounded_icon=None, glyph=None)[source]

This represents a result that would be returned as a result for a query or context menu.

For simple useage: create instances of this class as-is.

For advanced useage (handling clicks and custom context menus), it is recommended to subclass the result object to create your own subclass.

Subclassing

Subclassing lets you override the following methods: callback() and context_menu(). It also lets you create “universal” result properties (eg: same icon). Example:

class MyResult(Result):
    def __init__(self, title: str) -> None:
        super().__init__(self, title, icon="Images/app.png")

    async def callback(self):
        # handle what happens when the result gets clicked

    async def context_menu(self):
        # add context menu options to this result's context menu
title

The title/content of the result

Type:

str

sub

The subtitle to be shown.

Type:

Optional[str]

icon

A path to the icon to be shown with the result. If this and glyph are passed, the user’s Use Segoe Fluent Icons setting will determine which is used.

Type:

Optional[str]

title_highlight_data

The highlight data for the title. See the FAQ section on highlights for more info.

Type:

Optional[Iterable[int]]

title_tooltip

The text to be displayed when the user hovers over the result’s title

Type:

Optional[str]

sub_tooltip

The text to be displayed when the user hovers over the result’s subtitle

Type:

Optional[str]

copy_text

This is the text that will be copied when the user does CTRL+C on the result. If the text is a file/directory path, flow will copy the actual file/folder instead of just the path text.

Type:

Optional[str]

plugin

Your plugin instance. This is filled before callback() or context_menu() are triggered.

Type:

Plugin | None

preview

Customize the preview that is shown for the result. By default, the preview shows the result’s title, subtitle, and icon

Type:

Optional[ResultPreview]

progress_bar

The progress bar that could be shown in the place of the title

Type:

Optional[ProgressBar]

auto_complete_text

The text that will replace the raw_text in the flow menu when the autocomplete hotkey is used on the result. Defaults to the result’s title.

Type:

Optional[str]

rounded_icon

Whether to have round the icon or not.

Type:

Optional[bool]

glyph

The Glyph object that will serve as the result’s icon. If this and icon are passed, the user’s Use Segoe Fluent Icons setting will determine which is used.

Type:

Optional[Glyph]

await callback()[source]

This function is a coroutine.

Override this function to add a callback behavior to your result. This method will run when the user clicks on your result.

Changed in version 2.0.0: A result callback can not return bool or None

Returns:

ExecuteResponse | bool | None – A response to flow determining whether or not to hide flow’s menu, or a bool that will be turned into a response. None will be converted into True to align with the default value for hide

await context_menu()[source]

This function is a coroutine.

Override this function to add a context menu behavior to your result. This method will run when the user gets the context menu to your result.

This method can return/yield almost anything, and flogin will convert it into a list of Result objects before sending it to flow.

Returns:

list[Result] | Result | str | Any – A list of results, an results, or something that can be converted into a list of results.

Yields:

Result | str | Any – A result object or something that can be converted into a result object.

classmethod create_with_partial(partial_callback, **kwargs)[source]

A quick and easy way to create a result with a callback without subclassing.

Note

This is meant to be used with FlowLauncherAPI methods

Example

result = Result.create_with_partial(
    functools.partial(
        plugin.api.show_notification,
        "notification title",
        "notification content"
    ),
    title="Result title",
    sub="Result subtitle"
)
Parameters:
classmethod from_dict(data)[source]

Creates a Result from a dictionary

Note

This method does NOT fill the callback() or context_menu() attributes.

Parameters:

data (dict[str, Any]) – The valid dictionary that includes the result data

Raises:

KeyError – The dictionary did not include the only required field, title.

Returns:

Result

await on_context_menu_error(error)[source]

This function is a coroutine.

Override this function to add an error response behavior to this result’s context menu callback.

If the error was handled:

You can return/yield almost anything, and flogin will convert it into a list of Result objects before sending it to flow.

If the error was not handled:

Return a ErrorResponse object

Parameters:

error (Exception) – The error that occured

Returns:

ErrorResponse | list[Result] | Result | str | Any – A list of results, an results, or something that can be converted into a list of results.

Yields:

Result | str | Any – A result object or something that can be converted into a result object.

await on_error(error)[source]

This function is a coroutine.

Override this function to add an error response behavior to this result’s callback.

Parameters:

error (Exception) – The error that occured

to_dict()[source]

This converts the result into a json serializable dictionary

Returns:

dict[str, Any]

Attributes
class flogin.jsonrpc.results.ResultPreview(image_path, *, description=None, is_media=True)[source]

Represents a result’s preview.

Note

Previews are finicky, and may not work 100% of the time

image_path

The path to the image to be shown

Type:

str

description

The description to be shown

Type:

Optional[str]

is_media

Whther the preview should be treated as media or not

Type:

Optional[bool]

Attributes
class flogin.jsonrpc.results.ProgressBar(percentage, color=...)[source]

This represents the progress bar than can be shown on a result.

Note

Visually, the progress bar takes the same spot as the title

percentage

The percentage of the progress bar that should be filled. must be 0-100.

Type:

int

color

The color that the progress bar should be in hex code form. Defaults to #26a0da.

Type:

str

Attributes
Methods
class flogin.jsonrpc.results.Glyph(text, font_family)[source]

This represents a glyph object with flow launcher, which is an alternative to Result icons.

text

The text to be shown in the glyph

Type:

str

font_family

The font that the text should be shown in

Type:

str

classmethod from_dict(data)[source]

Converts a dictionary into a Glyph object.

Parameters:

data (dict[str, Any]) – The dictionary

typeddict flogin.jsonrpc.results.ResultConstructorKwargs[source]

This represents the possible kwargs that can be passed to Result.

This can be useful when overriding Result to create a basic implementation of something for your project, but still want the ability to pass kwargs with proper typing.

Note

See Result for more information about each key and value.

Example

This is an example of how you might use this to create a url result

from typing import Unpack
from flogin import Result, ResultConstructorKwargs

class MyRes(Result):
    def __init__(self, url: str, **kwargs: Unpack[ResultConstructorKwargs]) -> None:
        self.url = url
        super().__init__(**kwargs)

    async def callback(self):
        await self.plugin.api.open_url(self.url)
Optional Keys:

Responses

Attributes
class flogin.jsonrpc.responses.ErrorResponse[source]

This represents an error sent to or from flow.

code

The error code for the error

Type:

int

message

The error’s message

Type:

str

data

Any extra data

Type:

Optional[Any]

Attributes
class flogin.jsonrpc.responses.QueryResponse[source]

This response represents the response from search handler’s callbacks and context menus. See the search handler section for more information about using search handlers.

results

The results to be sent as the result of the query

Type:

list[Result]

settings_changes

Any changes to be made to the plugin’s settings.

Type:

dict[str, Any]

debug_message

A debug message if you want

Type:

str

Attributes
class flogin.jsonrpc.responses.ExecuteResponse[source]

This response is a generic response for jsonrpc requests, most notably result callbacks.

hide

Whether to hide the flow menu after execution or not

Type:

bool

Search Handlers

Attributes
Methods
class flogin.search_handler.SearchHandler[PluginT](condition=None, *, text=..., pattern=..., keyword=..., allowed_keywords=..., disallowed_keywords=...)[source]

This represents a search handler.

When creating this on your own, the register_search_handler() method can be used to register it.

See the search handler section for more information about using search handlers.

There is a provided decorator to easily create search handlers: search()

The keywords in the constructor can also be passed into the subclassed init, like so:

class MyHandler(SearchHandler, text="text"):
    ...

# is equal to

class MyHandler(SearchHandler):
    def __init__(self):
        super().__init__(text="text")
Parameters:

  • condition (Optional[condition]) – The condition to determine which queries this handler should run on. If given, this should be the only argument given.

  • text (Optional[str]) – A kwarg to quickly add a PlainTextCondition. If given, this should be the only argument given.

  • pattern (Optional[re.Pattern | str]) – A kwarg to quickly add a RegexCondition. If given, this should be the only argument given.

  • keyword (Optional[str]) – A kwarg to quickly set the condition to a KeywordCondition condition with the keyword kwarg being the only allowed keyword.

  • allowed_keywords (Optional[Iterable[str]]) – A kwarg to quickly set the condition to a KeywordCondition condition with the kwarg being the list of allowed keywords.

  • disallowed_keywords (Optional[Iterable[str]]) – A kwarg to quickly set the condition to a KeywordCondition condition with the kwarg being the list of disallowed keywords.

plugin

Your plugin instance. This is filled before callback() is triggered.

Type:

Plugin | None

@error[source]

A decorator that registers a error handler for this search handler.

For more information see on_error

Example

@plugin.search()
async def my_hander(query):
    ..

@my_handler.error
async def my_error_handler(query, error):
    ...
await callback(query)[source]

This function is a coroutine.

Override this function to add the search handler behavior you want for the set condition.

This method can return/yield almost anything, and flogin will convert it into a list of Result objects before sending it to flow.

Returns:

list[Result] | Result | str | Any – A list of results, an results, or something that can be converted into a list of results.

Yields:

Result | str | Any – A result object or something that can be converted into a result object.

condition(query)[source]

A function that determines whether or not to fire off this search handler for a given query

Parameters:

query (Query) – The query object for the query request

Returns:

bool – Whether or not to fire off this handler for the given query.

property name

The name of the search handler’s callback

Type:

str

await on_error(query, error)[source]

This function is a coroutine.

Override this function to add an error response behavior to this handler’s callback.

If the error was handled:

You can return/yield almost anything, and flogin will convert it into a list of Result objects before sending it to flow.

If the error was not handled:

Return a ErrorResponse object

Parameters:

  • query (Query) – The query that was being handled when the error occured.

  • error (Exception) – The error that occured

Returns:

ErrorResponse | list[Result] | Result | str | Any – A list of results, an results, or something that can be converted into a list of results.

Yields:

Result | str | Any – A result object or something that can be converted into a result object.

Builtin Search Conditions

Attributes
class flogin.conditions.PlainTextCondition(text)[source]

A builtin search condition to check plain text.

This condition will only run if the query’s text is the same as the text given to this condition. See the search handler section for more information about using search handlers and conditions.

text

The text to compare the query to

Type:

str

Attributes
class flogin.conditions.RegexCondition(pattern)[source]

A builtin search condition to check a regex pattern.

This condition will only run if the query’s text is a match to the regex pattern given to this condition. See the search handler section for more information about using search handlers and conditions.

This condition will set the query’s condition_data attribute to the re.Match object.

pattern

The pattern to check the queries against.

Type:

re.Pattern

Attributes
class flogin.conditions.KeywordCondition(*, allowed_keywords=None, disallowed_keywords=None)[source]

A builtin search condition to check what keyword was used with the query.

If the allowed_keywords attribute is given, the handler will only run if the query’s keyword is in the list of allowed keywords. If the disallowed_keywords attribute is given, the handler will only run if the query’s keyword is not in the list of allowed keywords.

See the search handler section for more information about using search handlers and conditions.

allowed_keywords

The allowed keywords

Type:

Optional[Iterable[str]]

disallowed_keywords

The disallowed keywords

Type:

Optional[Iterable[str]]

Attributes
class flogin.conditions.AllCondition(*conditions)[source]

This builtin search condition acts similiarly to the builtin all function. It only returns True if all of the given conditions also return True.

This condition will set flogin.query.Query.condition_data to a dictionary containing the conditions, where the keys are the conditions, and the values are the condition data that they gave.

conditions

A list that contains all the conditions that should be used with this condition.

Type:

list[condition]

Attributes
class flogin.conditions.AnyCondition(*conditions)[source]

This builtin search condition acts similiarly to the builtin any function. It only returns True if any one of the given conditions return True.

This condition will set flogin.query.Query.condition_data to a tuple containing two values. The first value will be the condition that returned true, and the second will be the condition data that the condition gave.

(condition, query.condition_data)
conditions

A list that contains all the conditions that should be used with this condition.

Type:

list[condition]

Flow

API

Methods
class flogin.flow.api.FlowLauncherAPI[source]

This class is a wrapper around Flow’s API to make it easy to make requests and receive results.

Note

Do not initialize this class yourself, instead use Plugin’s api attribute to get an instance.

await add_keyword(plugin_id, keyword)[source]

This function is a coroutine.

Registers a new keyword for a plugin with flow launcher.

Parameters:

  • plugin_id (str) – The id of the plugin that you want the keyword added to

  • keyword (str) – The keyword to add

Raises:

JsonRPCException – This is raised when an error happens with the JsonRPC pipe while attempting to call this API method.

Returns:

None

await change_query(new_query, requery=False)[source]

This function is a coroutine.

Change the query in flow launcher’s menu.

Parameters:

  • new_query (str) – The new query to change it to

  • requery (bool) – Whether or not to re-send a query request in the event that the new_query is the same as the current query

Raises:

JsonRPCException – This is raised when an error happens with the JsonRPC pipe while attempting to call this API method.

Returns:

None

await check_for_updates()[source]

This function is a coroutine.

This tells flow launcher to check for updates to flow launcher

Note

This tells flow launcher to check for updates to flow launcher, not your plugin

Raises:

JsonRPCException – This is raised when an error happens with the JsonRPC pipe while attempting to call this API method.

Returns:

None

This function is a coroutine.

Asks flow how similiar two strings are.

Parameters:

  • text (str) – The text

  • text_to_compare_it_to (str) – The text you want to compare the other text to

Raises:

JsonRPCException – This is raised when an error happens with the JsonRPC pipe while attempting to call this API method.

Returns:

FuzzySearchResult

await get_all_plugins()[source]

This function is a coroutine.

Get the metadata of all plugins that the user has installed

Raises:

JsonRPCException – This is raised when an error happens with the JsonRPC pipe while attempting to call this API method.

Returns:

list[PluginMetadata]

await hide_main_window()[source]

This function is a coroutine.

This method tells flow to hide the main window

Raises:

JsonRPCException – This is raised when an error happens with the JsonRPC pipe while attempting to call this API method.

Returns:

None

await is_main_window_visible()[source]

This function is a coroutine.

This method asks flow if the main window is visible or not

Raises:

JsonRPCException – This is raised when an error happens with the JsonRPC pipe while attempting to call this API method.

Returns:

bool

await open_directory(directory, file=None)[source]

This function is a coroutine.

Opens up a folder in file explorer. If a file is provided, the file will be pre-selected.

Parameters:

  • directory (str) – The directory you want to open

  • file (Optional[str]) – The file in the directory that you want to highlight, defaults to None

Raises:

JsonRPCException – This is raised when an error happens with the JsonRPC pipe while attempting to call this API method.

Returns:

None

await open_settings_menu()[source]

This function is a coroutine.

This method tells flow to open up the settings menu.

Raises:

JsonRPCException – This is raised when an error happens with the JsonRPC pipe while attempting to call this API method.

Returns:

None

await open_url(url, in_private=False)[source]

This function is a coroutine.

Open up a url in the user’s preferred browser, which was set in their Flow Launcher settings.

Parameters:

  • url (str) – The url to be opened in the webbrowser

  • in_private (bool) – Whether or not to open up the url in a private window

Raises:

JsonRPCException – This is raised when an error happens with the JsonRPC pipe while attempting to call this API method.

Returns:

None

await reload_all_plugin_data()[source]

This function is a coroutine.

This method tells flow to trigger a reload of all plugins.

Raises:

JsonRPCException – This is raised when an error happens with the JsonRPC pipe while attempting to call this API method.

Returns:

None

await remove_keyword(plugin_id, keyword)[source]

This function is a coroutine.

Unregisters a keyword for a plugin with flow launcher.

Parameters:

  • plugin_id (str) – The ID of the plugin that you want to remove the keyword from

  • keyword (str) – The keyword that you want to remove

Raises:

JsonRPCException – This is raised when an error happens with the JsonRPC pipe while attempting to call this API method.

Returns:

None

await restart_flow_launcher()[source]

This function is a coroutine.

This method tells flow launcher to initiate a restart of flow launcher.

Warning

Expect this method to never finish, so clean up and prepare for the plugin to be shut down before calling this.

Raises:

JsonRPCException – This is raised when an error happens with the JsonRPC pipe while attempting to call this API method.

await run_shell_cmd(cmd, filename='cmd.exe')[source]

This function is a coroutine.

Tell flow to run a shell command

Parameters:

  • cmd (str) – The command to be run

  • filename (str) – The name of the command prompt instance, defaults to cmd.exe

Raises:

JsonRPCException – This is raised when an error happens with the JsonRPC pipe while attempting to call this API method.

Returns:

None

await save_all_app_settings()[source]

This function is a coroutine.

This method tells flow to save all app settings.

Raises:

JsonRPCException – This is raised when an error happens with the JsonRPC pipe while attempting to call this API method.

Returns:

None

await save_plugin_settings()[source]

This function is a coroutine.

This method tells flow to save plugin settings

Raises:

JsonRPCException – This is raised when an error happens with the JsonRPC pipe while attempting to call this API method.

Returns:

None

await show_error_message(title, text)[source]

This function is a coroutine.

Triggers an error message in the form of a windows notification

Parameters:

  • title (str) – The title of the notification

  • text (str) – The content of the notification

Raises:

JsonRPCException – This is raised when an error happens with the JsonRPC pipe while attempting to call this API method.

Returns:

None

await show_main_window()[source]

This function is a coroutine.

This method tells flow to show the main window

Raises:

JsonRPCException – This is raised when an error happens with the JsonRPC pipe while attempting to call this API method.

Returns:

None

await show_notification(title, content, icon='', use_main_window_as_owner=True)[source]

This function is a coroutine.

Creates a notification window in the bottom right hand of the user’s screen

Parameters:

  • title (str) – The notification’s title

  • content (str) – The notification’s content

  • icon (str) – The icon to be shown with the notification, defaults to “”

  • use_main_window_as_owner (bool) – Whether or not to use the main flow window as the notification’s owner. Defaults to True

Raises:

JsonRPCException – This is raised when an error happens with the JsonRPC pipe while attempting to call this API method.

Returns:

None

await update_results(raw_query, results)[source]

This function is a coroutine.

Tells flow to change the results shown to the user

Note

The raw_query parameter is required by flow launcher, and must be the same as the current raw query in flow launcher for the results to successfully update.

Parameters:

  • raw_query (str) – Only change the results if the current raw query is the same as this

  • results (list[Result]) – The new results

Raises:

JsonRPCException – This is raised when an error happens with the JsonRPC pipe while attempting to call this API method.

Returns:

None

Attributes
class flogin.flow.fuzzy_search.FuzzySearchResult[source]

A class which represents the result given from flow launcher to a fuzzy search request

Note

This is not intended to be a class that you create yourself, use fuzzy_search() instead.

score

The score of the result

Type:

int

highlight_data

The highlight data included with the result

Type:

list[int]

search_percision

The perision of the result

Type:

int

Attributes
Methods
class flogin.flow.plugin_metadata.PluginMetadata[source]

This class represents a plugin’s metadata

id

The plugin’s ID

Type:

str

name

The plugin’s name

Type:

str

author

The name of the plugin’s author

Type:

str

version

The current version of the plugin

Type:

str

language

The language that the plugin is written in. Possible values: “csharp”, “executable”, “fsharp”, “python”, “javascript”, “typescript”, “python_v2”, “executable_v2”, “javascript_v2”, “typescript_v2”.

Type:

str

description

The plugin’s description

Type:

str

website

A link to the plugin’s website

Type:

str

disabled

Whether the plugin is disabled or not

Type:

bool

directory

The path to the plugin’s directory

Type:

str

keywords

A list of the plugin’s keywords

Type:

list[str]

main_keyword

The plugin’s main keyword

Type:

str

add_keyword(keyword)[source]

This function is a coroutine.

Registers a new keyword with flow for the plugin.

This is a shortcut to add_keyword()

Parameters:

keyword (str) – The keyword to be added

Raises:

JsonRPCException – This is raised when an error happens with the JsonRPC pipe while attempting to call this API method.

Returns:

None

property executable

The path to the plugin’s executable file

Type:

pathlib.Path

property icon

The path to the plugin’s icon file

Type:

pathlib.Path

remove_keyword(keyword)[source]

This function is a coroutine.

Removes a keyword from the plugin.

This is a shortcut to remove_keyword()

Parameters:

keyword (str) – The keyword to be removed

Raises:

JsonRPCException – This is raised when an error happens with the JsonRPC pipe while attempting to call this API method.

Returns:

None

Settings

Attributes
class flogin.flow.settings.FlowSettings[source]

This is a class which represents the settings that flow launcher saves in config files.

hotkey
Type:

str

open_result_modifiers
Type:

str

color_scheme
Type:

str

show_open_result_gotkey
Type:

bool

window_size
Type:

int | float

preview_hotkey
Type:

str

autocomplete_hotkey
Type:

str

autocomplete_hotkey_2
Type:

str

select_next_item_hotkey
Type:

str

select_next_item_hotkey_2
Type:

str

select_previous_item_hotkey
Type:

str

select_previous_item_hotkey_2
Type:

str

select_next_page_hotkey
Type:

str

select_previous_page_hotkey
Type:

str

open_context_menu_hotkey
Type:

str

setting_window_hotkey
Type:

str

cycle_history_up_hotkey
Type:

str

cycle_history_down_hotkey
Type:

str

language
Type:

str

theme
Type:

str

use_drop_shadow_effect
Type:

bool

window_height_size
Type:

int | float

item_height_size
Type:

int | float

query_box_font_size
Type:

int | float

result_item_font_size
Type:

int | float

result_sub_item_font_size
Type:

int | float

query_box_font
Type:

str | None

query_box_font_style
Type:

str | None

query_box_font_weight
Type:

str | None

query_box_font_stretch
Type:

str | None

result_font
Type:

str | None

result_font_style
Type:

str | None

result_font_weight
Type:

str | None

result_font_stretch
Type:

str | None

result_sub_font
Type:

str | None

result_sub_font_style
Type:

str | None

result_sub_font_weight
Type:

str | None

result_sub_font_stretch
Type:

str | None

use_glyph_icons
Type:

bool

use_animation
Type:

bool

use_sound
Type:

bool

sound_volume
Type:

int | float

use_clock
Type:

bool

use_date
Type:

bool

time_format
Type:

str

date_format
Type:

str

first_launch
Type:

bool

setting_window_width
Type:

int | float

setting_window_height
Type:

int | float

setting_window_top
Type:

int | float | None

setting_window_left
Type:

int | float | None

setting_window_state
Type:

int

custom_explorer_index
Type:

int

custom_explorer_list
Type:

list[CustomFileManager]

custom_browser_index
Type:

int

custom_browser_list
Type:

list[CustomBrowser]

should_use_pinyin
Type:

bool

always_preview
Type:

bool

always_start_en
Type:

bool

query_search_precision
Type:

SearchPrecisionScore

auto_updates
Type:

bool

window_left
Type:

int | float

window_top
Type:

int | float

custom_window_left
Type:

int | float

custom_window_top
Type:

int | float

keep_max_results
Type:

bool

max_results_to_show
Type:

int

activate_times
Type:

int

custom_plugin_hotkeys
Type:

list[CustomPluginHotkey]

custom_shortcuts
Type:

list[CustomQueryShortcut]

dont_prompt_update_msg
Type:

bool

enable_update_log
Type:

bool

start_flow_launcher_on_system_startup
Type:

bool

hide_on_startup
Type:

bool

hide_notify_icon
Type:

bool

leave_cmd_open
Type:

bool

hide_when_deactivated
Type:

bool

search_window_screen
Type:

SearchWindowScreens

search_window_align
Type:

SearchWindowAligns

custom_screen_number
Type:

int

ignore_hotkeys_on_fullscreen
Type:

bool

proxy
Type:

HttpProxy

last_query_mode
Type:

LastQueryMode

animation_speed
Type:

AnimationSpeeds

custom_animation_length
Type:

int

plugin_settings
Type:

PluginsSettings

Attributes
class flogin.flow.settings.CustomQueryShortcut[source]

This is a replica of the CustomShortcutModel dataclass in flow.

This represents a custom shortcut in flow’s config file.

value

The shortcut’s value, which in the ui is called the Expansion

Type:

str

key

The shortcut’s key, which in the ui is called the Shortcut`

Type:

str

Attributes
class flogin.flow.settings.CustomFileManager[source]

This is a replica of the CustomExplorerViewModel dataclass in flow.

This is an entry for a custom file manager, which is under the Default File Manager option in flow’s ui settings.

name

The name of the filemanager

Type:

str

path

The path to the filemanager

Type:

str

file_argument

How to tell the filemanager which file to open

Type:

str

directory_argument

How to tell the filemanager which directory to open

Type:

str

editable

Whether or not the user can edit this entry in the ui

Type:

bool

Attributes
class flogin.flow.settings.CustomBrowser[source]

This is a replica of the CustomBrowserViewModel dataclass in flow.

This represents an entry for a custom browser, which is under the Default Web Browser option in flow’s ui settings.

name

The name of the browser

Type:

str

path

The path to the browser’s executable

Type:

str

private_arg

The argument that is used to tell the browser to open in incognito/private mode

Type:

str

enable_private

Whether or not to open the browser in private/incognito mode

Type:

bool

open_in_tab

Whether to open the link in a new tab or browser window

Type:

bool

editable

Whether the user can edit this entry in the ui

Type:

bool

Attributes
class flogin.flow.settings.CustomPluginHotkey[source]

This is a replica of the CustomPluginHotkey dataclass in flow.

hotkey
Type:

str

keyword
Type:

str

Attributes
class flogin.flow.settings.HttpProxy[source]

This represents the user’s proxy info

enabled

Whether or not the proxy is active

Type:

bool

server

The proxy’s server

Type:

str | None

port

The proxy’s port

Type:

int | None

username

The proxy’s username

Type:

str | None

password

The proxy’s password

Type:

str | None

Attributes
class flogin.flow.settings.PartialPlugin[source]

This is a partial plugin from flow.

id

The plugin’s ID

Type:

str

name

The plugin’s name

Type:

str

version

The plugin’s version

Type:

str

priority

The plugin’s priority

Type:

int

disabled

Whether or not the plugin is disabled

Type:

bool

keywords

The plugin’s keywords

Type:

list[str]

Attributes
class flogin.flow.settings.PluginsSettings[source]

This represents the user’s plugin settings from the general flow config file.

python_executable

The location of the user’s python executable. If there is none, this attribute will be an empty string.

Type:

str

node_executable

The location of the user’s node executable. If there is none, this attribute will be an empty string.

Type:

str

plugins

A list of the user’s plugins, in partial form.

Type:

list[PartialPlugin]

class flogin.flow.settings.LastQueryMode[source]
class flogin.flow.settings.SearchWindowScreens[source]
class flogin.flow.settings.SearchWindowAligns[source]
class flogin.flow.settings.AnimationSpeeds[source]
class flogin.flow.settings.SearchPrecisionScore[source]

Errors

Plugin Errors

exception flogin.errors.PluginException[source]

Bases: Exception

A class that represents exceptions with your plugin

exception flogin.errors.PluginNotInitialized[source]

Bases: PluginException

This is raised when you try to access something that needs data from the initialize method, and it hasn’t been called yet.

Attributes
exception flogin.errors.EnvNotSet[source]

Bases: PluginException

This is raised when an environment variable that flow automatically sets is not set and can not be retrieved. This should only get raised when your plugin gets run, but not by flow.

name

The name of the environment variable that was not found

Type:

str

alternative

Optionally, the name of the keyword argument in the PluginTester constructor that will set the variable for you.

Type:

Optional[str]

JSON-RPC Errors

Attributes
exception flogin.jsonrpc.errors.JsonRPCException(message, data=None)[source]

Bases: Exception

This is a generic class representing a JsonRPCException

code

The JsonRPC Error Code

Type:

int

message

The message sent with the error

Type:

str

data

Any data sent with the error

Type:

Optional[Any]

Attributes
exception flogin.jsonrpc.errors.ParserError(message, data=None)[source]

Bases: JsonRPCException

This is a specialized JsonRPCException specifically for the error code -32700, which should mean that flogin sent invalid data and flow was unable to parse it.

code

The JsonRPC Error Code

Type:

int = -32700

message

The message sent with the error

Type:

str

data

Any data sent with the error

Type:

Optional[Any]

Attributes
exception flogin.jsonrpc.errors.InvalidRequest(message, data=None)[source]

Bases: JsonRPCException

This is a specialized JsonRPCException specifically for the error code -32600, which should mean that flogin sent an invalid request object.

code

The JsonRPC Error Code

Type:

int = -32600

message

The message sent with the error

Type:

str

data

Any data sent with the error

Type:

Optional[Any]

Attributes
exception flogin.jsonrpc.errors.MethodNotFound(message, data=None)[source]

Bases: JsonRPCException

This is a specialized JsonRPCException specifically for the error code -32601, which should mean that flogin is attempting to use a method that doesn’t exist.

code

The JsonRPC Error Code

Type:

int = -32601

message

The message sent with the error

Type:

str

data

Any data sent with the error

Type:

Optional[Any]

Attributes
exception flogin.jsonrpc.errors.InvalidParams(message, data=None)[source]

Bases: JsonRPCException

This is a specialized JsonRPCException specifically for the error code -32602, which should mean that flogin is attempting to use a method, but is sending the wrong parameters.

code

The JsonRPC Error Code

Type:

int = -32602

message

The message sent with the error

Type:

str

data

Any data sent with the error

Type:

Optional[Any]

Attributes
exception flogin.jsonrpc.errors.InternalError(message, data=None)[source]

Bases: JsonRPCException

This is a specialized JsonRPCException specifically for the error code -32603, which should mean that flogin has received an error.

code

The JsonRPC Error Code

Type:

int = -32603

message

The message sent with the error

Type:

str

data

Any data sent with the error

Type:

Optional[Any]

Attributes
exception flogin.jsonrpc.errors.FlowError(message, data=None)[source]

Bases: JsonRPCException

This is a specialized JsonRPCException specifically for error codes between -32000 and -32099, which means that flow has ran into an error.

code

The JsonRPC Error Code

Type:

int

message

The message sent with the error

Type:

str

data

Any data sent with the error

Type:

Optional[Any]

Pip Errors

exception flogin.errors.PipException[source]

Bases: Exception

This is a base class to represent errors derived from the Pip object.

Added in version 2.0.0.

Attributes
exception flogin.errors.UnableToDownloadPip[source]

Bases: PipException

This is an exception which is used to indicate that an error occurred while attempting to download pip.

Added in version 2.0.0.

error

The error that was raised by the Requests: HTTP for Humans™ module.

Type:

requests.exceptions.HTTPError | requests.Timeout | requests.ConnectionError

Attributes
exception flogin.errors.PipExecutionError[source]

Bases: PipException

This is an exception which is raised whenever flogin.pip.Pip.run() gets a return code that isn’t 0.

Added in version 2.0.0.

error

The original error that was raised by subprocess

Type:

subprocess.CalledProcessError

property output

str The output from subprocess.CalledProcessError.output

property returncode

int The returncode from subprocess.CalledProcessError.returncode

property stderr

str The stderr from subprocess.CalledProcessError.stderr

Testing

Attributes
Methods
class flogin.testing.plugin_tester.PluginTester[PluginT](plugin, *, metadata, flow_api_client=..., flow_version=..., flow_application_dir=..., flow_program_dir=...)[source]

This can be used to write tests for your plugins.

See the Testing your plugin guide for more information on writing tests.

Parameters:

  • plugin (Plugin) – Your plugin

  • metadata (PluginMetadata | dict[str, Any] | None) – Your plugin’s metadata. If None is passed, flogin will attempt to get the metadata from your plugin.json file. The PluginTester.create_plugin_metadata() and PluginTester.create_bogus_plugin_metadata() classmethods have been provided for creating PluginMetadata objects.

  • flow_api_client (Optional[Any]) – If not passed, flogin will use a filler class which will raise a runtime error whenever an attribute is accessed. If passed, you should be passing an instance of a class which will replace FlowLauncherAPI, so make sure to implement the methods you need and handle them accordingly.

  • flow_version (Optional[str]) –

    This is an optional positional keyword that if set, will automatically set the enviroment variable FLOW_VERSION to the value. This is useful if your code uses the flow_version property.

  • flow_application_dir (Optional[str | Path]) –

    This is an optional positional keyword that if set, will automatically set the enviroment variable FLOW_APPLICATION_DIRECTORY to the value. This is useful if your code uses the flow_application_dir property.

  • flow_program_dir (Optional[str | Path]) –

    This is an optional positional keyword that if set, will automatically set the enviroment variable FLOW_PROGRAM_DIRECTORY to the value. This is useful if your code uses the flow_program_dir property.

plugin

Your plugin

Type:

Plugin

classmethod create_bogus_plugin_metadata()[source]

This classmethod can be used to easily and quickly create a PluginMetadata object that can be used for testing.

Note

Since the information that this classmethod generates is bogus, it is not recommended to use this when your plugin relies on the plugin metadata. Consider using PluginTester.create_plugin_metadata() instead.

Returns:

PluginMetadata – The PluginMetadata instance with your bogus information.

classmethod create_plugin_metadata(*, id, name, author, version, description, website=None, disabled=False, directory=None, keywords=None, main_keyword=None, icon_path=None)[source]

This classmethod can be used to easily create a valid PluginMetadata object that has correct data.

Parameters:

  • id (str) – The plugin’s id

  • name (str) – The plugin’s name

  • author (str) – The plugin’s author

  • version (str) – The plugin’s version

  • description (str) – The plugin’s description

  • website (Optional[str]) – The plugin’s website. If not given, the following fstring will be used instead: f"https://github.com/{author}/{name}"

  • disabled (Optional[bool]) – Whether or not to mark the plugin as disabled. Defaults to False

  • directory (Optional[str]) – The plugin’s directory. Defaults to the current working directory.

  • keywords (Optional[list[str]]) – The plugin’s keywords. Defaults to ["*"]

  • main_keyword (Optional[str]) – The plugin’s main keyword. Defaults to the first keyword in the keywords parameter

  • icon_path (Optional[str]) – The plugin’s icon. Defaults to an invalid icon path.

Returns:

PluginMetadata – Your new metadata class.

set_flow_api_client(flow_api_client=...)[source]

This sets the flow api client that the tests should use.

Parameters:

flow_api_client (Optional[Any]) – If not passed, flogin will use a filler class which will raise a runtime error whenever an attribute is accessed. If passed, you should be passing an instance of a class which will replace FlowLauncherAPI, so make sure to implement the methods you need and handle them accordingly.

await test_context_menu(result, *, bypass_registration=False)[source]

This function is a coroutine.

This coroutine can be used to send a result’s context menu, and get the response.

Note

You should use this to test your context menus instead of invoking them directly because this method implements the post-processing that flogin puts onto your context menu and query methods.

Parameters:

  • result (Result) – The result you want to invoke the context menu for.

  • bypass_registration (bool) – Whether or not to bypass the Result has not been registered error.

Raises:

ValueError – This will be raised when bypass_registration is set to False, and the given result has not been registered.

Returns:

QueryResponse – The query response object that would normally be sent to flow.

await test_query(text, *, keyword='*', is_requery=False, settings=...)[source]

This function is a coroutine.

This coroutine can be used to send your plugin a query, and get the response.

Parameters:

  • query (Query) – The query object that should be passed to your search handlers.

  • settings (Optional[Settings | dict[str, Jsonable] | None]) – This will represent the settings that flogin will use when executing your search handlers. If not passed, flogin will not use any settings. If None is passed, flogin will get the settings from the settings file (this is incompatible with PluginTester.create_bogus_plugin_metadata()). If a dict or Settings object is passed, those are the settings that will be put in settings before executing your search handlers.

Returns:

QueryResponse – The query response object that would normally be sent to flow.

Utils

flogin.utils.setup_logging(*, formatter=None, handler=None, logger=None)[source]

Sets up flogin’s default logger.

Changed in version 2.0.0: setup_logging() now returns tuple[logging.Logger, logging.Handler]

Parameters:

  • formatter (Optional[logging.Formatter]) – The formatter to use, incase you don’t want to use the default file formatter.

  • handler (Optional[logging.Handler]) –

    The handler object that should be added to the logger. Defaults to logging.handlers.RotatingFileHandler with the following arguments:

    filename="flogin.log", maxBytes=1000000, encoding="UTF-8", backupCount=1

    Added in version 2.0.0.

  • logger (Optional[logging.Logger]) –

    The logger object that the handler/formatter should be added to.

    Added in version 2.0.0.

Returns:

tuple[logging.Logger, logging.Handler] – The logger and handler used to setup the logs.

await flogin.utils.coro_or_gen(coro)[source]

This function is a coroutine.

Executes an AsyncIterable or a Coroutine, and returns the result

Parameters:

coro (typing.Awaitable | typing.AsyncIterable) – The coroutine or asynciterable to be ran

Raises:

TypeError – Neither a typing.Coroutine or an typing.AsyncIterable was passed

Returns:

Any – Whatever was given from the typing.Coroutine or typing.AsyncIterable.

flogin.utils.print(*values, sep=..., name=...)[source]

A function that acts similar to the builtin print function, but uses the logging module instead.

This helper function is provided to easily “print” text without having to setup a logging object, because the builtin print function does not work as expected due to the jsonrpc pipes.

Added in version 1.1.0.

Changed in version 2.0.0: The default log name now defaults to the filepath of the file that called the function opposed to printing.

Parameters:

  • *values (object) – A list of values to print

  • sep (Optional[str]) – The character that is used as the seperator between the values. Defaults to a space.

  • name (Optional[str]) –

    The name of the logger. Defaults to the filepath of the file the function is called from.

    Added in version 2.0.0.

flogin.utils.MISSING

A type safe sentinel used in the library to represent something as missing. Used to distinguish from None values.

Pip

Attributes
Methods
class flogin.pip.Pip(libs_dir='lib')[source]

This is a helper class for dealing with pip in a production environment.

When flow launcher installs python, it does not install pip. Because of that, this class will temp-install pip while you need it, then delete it when you’re done with it.

Added in version 2.0.0.

Warning

This class is blocking, and should only be used before you load your plugin.

Parameters:

libs_dir (Optional[pathlib.Path | str]) – The directory that your plugin’s dependencies are installed to. Defaults to lib.

Example

This should be used before your plugin gets loaded. Here is an example of what your main file might look like when using pip:

# Add your paths
sys.path.append(...)
sys.path.append(...)

from flogin import Pip

with Pip() as pip:
    pip.ensure_installed("msgspec") # ensure the msgspec package is installed correctly

# import and run your plugin
from plugin.plugin import YourPlugin
YourPlugin().run()
with Pip(...) as pip:

Pip can be used as a context manager, with Pip.download_pip() being called on enter and Pip.delete_pip() being called on exit.

delete_pip()[source]

Deletes the temp version of pip installed on the system.

Note

This is automatically called when using Pip as a context manager.

Returns:

None

download_pip()[source]

Downloads the temp version of pip from pypa.

Note

This is automatically called when using Pip as a context manager.

Raises:

UnableToDownloadPip – This is raised when an error occured while attempting to download pip.

Returns:

None

ensure_installed(package, *, module=None)[source]

Ensures a package is properly installed, and if not, reinstalls it.

Parameters:

  • package (str) – The name of the package on PyPi that you want to install.

  • module (Optional[str]) – The name of the module you want to check to see if its installed. Defaults to the package value.

Raises:

PipException – This is raised when the returncode that pip gives indicates an error.

Returns:

bool – True indicates that the package wasn’t properly installed, and was successfully reinstalled. False indicates that the package was already properly installed.

freeze()[source]

Returns a list of installed packages from pip freeze.

Note

The directory checked for packages is set in Pip.libs_dir.

Raises:

PipException – This is raised when the returncode that pip gives indicates an error.

Returns:

list[str] – The list of packages and versions.

install_packages(*packages)[source]

An easy way to install packages for your plugin.

Note

The packages will be installed to the directory set in Pip.libs_dir.

Parameters:

*packages (str) – The name of the packages on PyPi that you want to install.

Raises:

PipException – This is raised when the returncode that pip gives indicates an error.

Returns:

None

property libs_dir

The directory that your plugin’s dependencies are installed to.

Type:

pathlib.Path

run(*args)[source]

Runs a pip CLI command.

This method is used to interact directly with pip.

Note

This method can not be used until download_pip() is ran, which you can do by calling it manually or using Pip as a context manager.

Parameters:

*args (str) – The args that should be passed to pip. Ex: help.

Raises:
Returns:

str – The output from pip.

Caching

@flogin.caching.cached_property(obj=None)[source]

A decorator that is similar to the builtin functools.cached_property decorator, but is async-safe and implements the ability to use clear_cache().

This decorator can also be called with the optional positional argument acting as a name argument. This is useful when using clear_cache() as it lets you choose which items you want to clear the cache of.

Example

class X:
    @cached_property
    def test(self):
        ...

class X:
    @cached_property("test_prop")
    def test(self):
        ...
@flogin.caching.cached_coro(obj=None)[source]

A decorator to cache a coroutine’s contents based on the passed arguments. This decorator can also be called with the optional positional argument acting as a name argument. This is useful when using clear_cache() as it lets you choose which items you want to clear the cache of.

Note

The arguments passed to the coroutine must be hashable.

Example

@plugin.search()
@cached_coro
async def handler(query):
    ...

@plugin.search()
@cached_coro("search-handler")
async def handler(query):
    ...
@flogin.caching.cached_gen(obj=None)[source]

A decorator to cache the contents of an async generator based on the passed arguments. This decorator can also be called with the optional positional argument acting as a name argument. This is useful when using clear_cache() as it lets you choose which items you want to clear the cache of.

Note

The arguments passed to the generator must be hashable.

Example

@plugin.search()
.cached_gen
async def handler(query):
    ...

@plugin.search()
@cached_gen("search-handler")
async def handler(query):
    ...
@flogin.caching.cached_callable(obj=None)[source]

A decorator to cache a callable’s output based on the passed arguments. This decorator can also be called with the optional positional argument acting as a name argument. This is useful when using clear_cache() as it lets you choose which items you want to clear the cache of.

Note

The arguments passed to the callable must be hashable.

Example

@cached_callable
def foo(bar):
    ...

@cached_callable("search-handler")
def foo(bar):
    ...
flogin.caching.clear_cache(key=...)[source]

This function is used to clear the cache of items that have been cached with this module.

The caching decorators provide an optional positional argument that acts as a name argument, which is used in combination of this function.

Parameters:

key (Optional[str | None]) – If str is passed, every cached item with a name equal to key will have their cache cleared. If None is passed, every cached item with a name equal to None will have their cache cleared (default value for a cached item’s name is None). Lastly, if the key parameter is not passed at all, all caches will be cleared.