Keypirinha

https://keypirinha.com/
Admin
Keypirinha is a fast launcher for keyboard ninjas on Windows that helps users quickly find and...
Tokens:43,795
Snippets:562
Trust Score:8.9
Update:5 months ago
Show doc for...
Tokens:
Raw
### Keypirinha INI File Example with Variables and Comments

Source: https://keypirinha.com/configuration.html

This example demonstrates Keypirinha's INI file format, including comments, variable assignments, and multiline values using indentation. It utilizes ExtendedInterpolation for variable substitution.

```ini
# This is a comment line so I can write whatever I want

[config]
# Values defined below belong to the 'config' section
boolean_value = yes
editor = ${var:my_editor}
say_hello = ${var:hello} World
multiline_setting =
    ${say_hello}
    This is a multiple line value.
    You can add as much lines as desired.
    As long as they are indented deeper than the first line of the value.

[var]
# Reusable values are grouped into the 'var' section
my_editor = D:/Apps/MyEditor/ShinyEditor.exe
hello = Hello

```

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

### Using Keypirinha Predefined Variable APP_DIR

Source: https://keypirinha.com/configuration.html

This example demonstrates how to use the predefined `APP_DIR` variable to specify the path to an external editor in the `external` section of the configuration.

```ini
# Example of using a variable predefined by Keypirinha
[external]
editor = "${var:APP_DIR}\..\MyEditor\MyEditor.exe"
```

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

### Google Translate Search Grammar Examples

Source: https://keypirinha.com/packages/googletranslate.html

Examples demonstrating how to use different grammars to specify source and target languages for translation queries. These grammars can override default item configurations.

```text
1. fr:en Bonjour
2. :es Danke
3. en: Hello world
4. hello world en:
5. Que tal? -:en
```

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

### Configure Multi-URL Search Site

Source: https://keypirinha.com/packages/websearch.html

Example configuration for a search site that uses multiple URLs. Keypirinha will cycle through these URLs for the search. Ensure proper indentation for URLs.

```ini
[site/Multi]
url =
    https://duckduckgo.com/?q=%s
    https://encrypted.google.com/search?q=%s

```

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

### keypirinha.installed_package_dir(package_full_name)

Source: https://keypirinha.com/api/module.html

Gets the path of an installed package or the base directory for installed packages.

```APIDOC
## keypirinha.installed_package_dir(package_full_name =None)

### Description
Get the path of an _installed_ package (i.e.: `*.keypirinha-package`), or the base directory for Installed Packages (Downloaded) if _package_full_name_ is not specified.

### Parameters
- **package_full_name** (str, optional) - The full name of the package.

### Notes
The base directory should look similar to `%APPDATA%/Keypirinha/InstalledPackages` in installed mode and `X:/Keypirinha/portable/Profile/InstalledPackages` in portable mode. The base directory is guaranteed to exist, but not the package itself. Thus it is the responsibility of the caller to create it if needed.
```

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

### keypirinha.live_package_dir(package_full_name)

Source: https://keypirinha.com/api/module.html

Gets the directory of a live package or the base directory for live packages.

```APIDOC
## keypirinha.live_package_dir(package_full_name =None)

### Description
Get the directory of a _live_ package, or the base directory for Live Packages in case _package_full_name_ is not specified.

### Parameters
- **package_full_name** (str, optional) - The full name of the package.

### Notes
Prefer to use `Plugin.get_package_cache_path()` when possible. The base directory should look similar to `%APPDATA%/Keypirinha/Packages` in installed mode and `X:/Keypirinha/portable/Profile/Packages` in portable mode. The base directory is guaranteed to exist, but not the directory of the given package. Thus it is the responsibility of the caller to create it if needed.
```

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

### Get Keypirinha Version as String

Source: https://keypirinha.com/api/module.html

Returns the application's version as a dotted string (e.g., 'M.mm.pppp'). Prefer `version()` for version comparisons.

```python
keypirinha.version_string()
```

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

### keypirinha_util.shell_url_scheme_to_command

Source: https://keypirinha.com/api/module-util.html

Gets the system's default command line associated with given URL schemes and the location of its default icon.

```APIDOC
## keypirinha_util.shell_url_scheme_to_command(url_scheme)

### Description
Get system’s default command line associated with the given URL scheme(s); and the location of its default icon.

### Parameters
#### Path Parameters
- **url_scheme** (str) - Required - The URL scheme name (e.g. “http”, “ftp”, “mailto”, “skype”, …). This argument **can also be an iterable** of URL schemes, in which case this function iterates over the given schemes until it finds a valid associated command line.

### Returns
The command line associated with the scheme and the shell location string of class’ default icon.

### Return Type
tuple

### See Also
`cmdline_split()`
```

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

### Configure Tools Profile with Recursion and Depth Limit

Source: https://keypirinha.com/packages/filescatalog.html

This example demonstrates a profile for cataloging executable tools. It scans multiple paths, including recursive scanning of a subdirectory using '**'. The 'max_depth' option limits the recursion level to 3, and the profile inherits settings from a predefined 'ExeOnly' profile.

```ini
[profile/Tools]
activate = yes
paths =
    C:\Git
    C:\MyScripts\**
inherit = ExeOnly
max_depth = 3

```

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

### Add Multiple Settings to GUI Section

Source: https://keypirinha.com/configuration.html

If a section already exists in your configuration file, you can add more settings under it without repeating the section header. This example shows how to set 'show_on_taskbar' and 'max_results'.

```ini
[gui]
show_on_taskbar = no
max_results = 90

```

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

### Get User Configuration Directory Path

Source: https://keypirinha.com/api/module.html

Returns the path to the directory where user-specific configuration files are stored. This path is guaranteed to exist and varies between installed and portable modes.

```python
keypirinha.user_config_dir()
```

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

### Scan Directory Example

Source: https://keypirinha.com/api/module-util.html

Demonstrates how to construct the full path of a found file or directory using the result of scan_directory. This function is deprecated in favor of os.scandir().

```python
root_dir = "c:/dir"
files = keypirinha.scan_directory(root_dir)
if len(files) > 0:
    full_path = os.path.join(root_dir, files[0])
```

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

### keypirinha.user_config_dir()

Source: https://keypirinha.com/api/module.html

Retrieves the path to the directory dedicated to user configuration. This directory is guaranteed to exist and its location depends on whether Keypirinha is installed or running in portable mode.

```APIDOC
## keypirinha.user_config_dir()

### Description
Get the path to the directory dedicated to user’s configuration.

### Method
keypirinha.user_config_dir()

### Parameters
None

### Returns
- **str**: The absolute path to the user configuration directory.

### Response Example
```json
"C:\\Users\\Username\\AppData\\Roaming\\Keypirinha\\User"
```
```

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

### Configure DuckDuckGo Search Site

Source: https://keypirinha.com/packages/websearch.html

Example configuration for adding a new search site, DuckDuckGo, to Keypirinha's WebSearch package. This defines the URL, new window behavior, incognito mode, and history retention.

```ini
[site/DuckDuckGo]
url = https://duckduckgo.com/?q=%s
new_window = yes
incognito = no
history_keep = all

```

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

### Define Custom WebSuggest Provider

Source: https://keypirinha.com/packages/websuggest.html

Example of defining a new custom suggestions provider for the WebSuggest package. This configuration specifies the API endpoint, arguments, and HTTP headers for the provider.

```ini
[provider/DuckDuckGo]
# Declare a new provider named "duckduckgo" (names are lowercased
# internally).
# A provider has two main groups of settings: for its *suggest API* and for
# the *browse* actions.

# Required: the *base* part of the URL to the API.
# It may contain the {terms} and {time} placeholders.
api_base = https://ac.duckduckgo.com/ac/

# Optional: the HTTP method used to reach the API (get or post)
# Default: get
api_method = get

# Optional: define the query part of the API URL by adding arguments.
# This is a multiline value that accepts a single ``name value`` pair per
# line. Values must not be URL-encoded yet.
api_args =
    q {terms}
    type list
    _ {time}

# Optional: it is possible to specify extra HTTP headers to be sent to the
# API.
# It is useful for example to prevent some providers to filter-out requests
# that do not seem to be issued by a regular browser (the Google Suggest API
# does that).
api_headers =
    User-Agent Mozilla/5.0

# Optional: the name of the parser used to read the response from the API.
# * There are two internal parsers at the moment, "opensearch" and "qwant".

```

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

### Get Keypirinha Version as Tuple

Source: https://keypirinha.com/api/module.html

Returns the application's version as a tuple of unsigned integers (major, minor, patch), suitable for direct version comparison.

```python
version() > (2, )
```

```python
version() <= (1, 1)
```

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

### keypirinha_util.web_browser_command

Source: https://keypirinha.com/api/module-util.html

A versatile function to manage web browser interactions, including opening URLs, getting command lines, and handling private mode and new windows.

```APIDOC
## keypirinha_util.web_browser_command(private_mode=None, new_window=None, url=None, execute=False)

### Description
A Swiss Knife function to deal with the web browser setup in Keypirinha’s global configuration (see the `web_browser` setting in the `[external]` section), or by default, with the system’s default web browser. This function allows to: Open the given URL, Get the split command line to execute the web browser, including the given URL, Get the split command line to execute the web browser, including a placeholder element to indicate where to insert the URL to open. All the above cases take the _private_mode_ and _new_window_ arguments into account. The execution flow of this function depends on the _url_ and _execute_ arguments only.

### Parameters
#### Path Parameters
- **private_mode** (bool) - Optional - Hint the browser you want to launch it in Private (or Incognito) mode. By default (i.e. `None`), this function will get user’s configuration, or will fall back to browser’s default behavior. Specifying a boolean value (other than `None`), will override user’s configuration.
- **new_window** (bool) - Optional - Hint the browser you want to launch a new window. By default (i.e. `None`), this function will get user’s configuration, or will fall back to browser’s default behavior. Specifying a boolean value (other than `None`), will override user’s configuration.
- **url** (str) - Optional - If specified, the given URL(s) will be inserted at the right place in the command line so the caller does not have to do it manually. This is convenient since, while being uncommon, the URL(s) might have to be inserted in the command line instead of just being appended. _url_ can also be an iterable of strings in case several URLs are to be launched, in which case, they will be opened together if possible (i.e. using the same command line).
- **execute** (bool) - Optional - Defaults to `False`. If `True`, the command line will be executed.

### Tip
_url_ can also be an iterable of strings in case several URLs are to be launched, in which case, they will be opened together if possible (i.e. using the same command line).
```

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

### Build and Use Urllib Opener with Keypirinha Settings

Source: https://keypirinha.com/api/module-net.html

Builds a urllib opener that respects Keypirinha's network settings. Use this to make HTTP requests within your plugin.

```python
opener = build_urllib_opener()
with opener.open("http://httpbin.org/user-agent") as response:
    print(response.read())
```

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

### package_cache_dir

Source: https://keypirinha.com/api/module.html

Gets the cache directory of a package or the base directory if package_full_name is not specified.

```APIDOC
## package_cache_dir

### Description
Gets the cache directory of a package, or its base directory if `package_full_name` is not specified. The base directory is guaranteed to exist.

### Parameters

#### Path Parameters
- **package_full_name** (str) – Optional - The name of the package for which to get the cache directory. If not specified, returns the base cache directory.

### Returns

- **str** - The path to the package's cache directory or the base cache directory.
```

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

### Load Settings

Source: https://keypirinha.com/api/plugin.html

Returns the `keypirinha.Settings` object associated with the parent Package, loading configuration data.

```APIDOC
## load_settings()

### Description
Return the `keypirinha.Settings` object associated with the parent Package.

### Note
- The configuration file(s) will be loaded only the first time this method is called. Any subsequent call will return a new `keypirinha.Settings` object pointing to the same data block.
```

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

### keypirinha.arch()

Source: https://keypirinha.com/api/module.html

Returns the current architecture model (e.g., 'x86' or 'x64').

```APIDOC
## keypirinha.arch()

### Description
Return current architecture model (i.e. `x86` or `x64`)

### Method
`keypirinha.arch()`
```

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

### package_name()

Source: https://keypirinha.com/api/plugin.html

Gets the package name of this plugin. Deprecated since version 2.9: Use `package_full_name()` instead.

```APIDOC
## package_name()

### Description
Get the package name of this plugin.

### Returns
- The package name (string).

### Deprecated
Deprecated since version 2.9: Use `package_full_name()` instead.
```

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

### Get Current User Name

Source: https://keypirinha.com/api/module.html

Retrieves the name of the current user, which is used for locating user-specific configuration files.

```python
keypirinha.user_name()
```

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

### build_urllib_opener

Source: https://keypirinha.com/api/module-net.html

Builds a urllib opener that incorporates Keypirinha's global network settings and provides a default timeout.

```APIDOC
## build_urllib_opener

### Description
A replacement to `urllib.request.build_opener()` that takes care of using current user’s global settings (Keypirinha and/or system’s) regarding network connections, by inserting and configuring one or several connection handlers (derived from `urllib.request.BaseHandler`).

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
- **proxies** (dict, optional) - Dictionary of proxy settings.
- **ssl_check_hostname** (bool, optional) - Whether to check SSL hostnames.
- **extra_handlers** (list, optional) - List of extra urllib handlers.
- **extra_pre_handlers** (list, optional) - List of extra pre-handlers for the opener.

### Request Example
```python
# example 1
opener = build_urllib_opener()
with opener.open("http://httpbin.org/user-agent") as response:
    print(response.read())
```

### Response
#### Success Response (200)
Returns a configured urllib opener object.

#### Response Example
```json
{
  "example": "configured opener object"
}
```
```

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

### Build Urllib Opener with HTTP Proxy

Source: https://keypirinha.com/api/module-net.html

Demonstrates how to create a urllib opener that uses a specified HTTP proxy for network requests. This is useful when your environment requires an HTTP proxy to access external resources.

```python
proxies = {'http': "http://proxy_user:proxy_pass@127.0.0.1:8080"}
opener = build_urllib_opener(proxies)
with opener.open("http://httpbin.org/ip") as response:
    print(response.read())
```

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

### Get Package Cache Path

Source: https://keypirinha.com/api/plugin.html

Returns the absolute path to the plugin's package cache directory. Optionally creates the directory if it does not exist.

```APIDOC
## get_package_cache_path(create=False)

### Description
Return the absolute path to package’s cache directory.

### Parameters
#### Path Parameters
- **create** (bool) - Optional - If True, create the directory if it does not exist. Defaults to False.

### Raises
- **RuntimeError** - Failed to get package’s cache directory
- **OSError** - Failed to create the directory (in case _create_ argument is `True`).
```

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

### Initialize Plugin - __init__

Source: https://keypirinha.com/api/plugin.html

Implement the default constructor for your plugin. It's good practice to call the superclass constructor using `super().__init__()`.

```python
def __init__(self):
    super().__init__()

```

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

### package_full_name()

Source: https://keypirinha.com/api/plugin.html

Gets the fully qualified name of this plugin’s parent package. Deprecated since version 2.9: Use `full_name()` instead.

```APIDOC
## package_full_name()

### Description
Get the fully qualified name of this plugin’s parent package.

### Returns
- The fully qualified package name (string).

### Deprecated
Deprecated since version 2.9: Use `full_name()` instead.
```

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

### keypirinha.exe_path()

Source: https://keypirinha.com/api/module.html

Returns the full path to Keypirinha’s bootstrap executable.

```APIDOC
## keypirahina.exe_path()

### Description
Return the full path to Keypirinha’s bootstrap executable (i.e. not the architecture-specific executable).

### Method
`keypirinha.exe_path()`
```

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

### Define a Simple Docs Profile

Source: https://keypirinha.com/packages/filescatalog.html

This snippet shows the most basic profile configuration. It defines a profile named 'Docs' that scans the immediate, non-hidden content of a specified directory non-recursively. The 'activate = yes' line is mandatory for the profile to be active.

```ini
[profile/Docs]
activate = yes
paths = C:\MyDocumentsFiles

```

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

### keypirinha.load_icon(sources, force_reload, package_full_name)

Source: https://keypirinha.com/api/module.html

Loads an icon and returns a handle to it.

```APIDOC
## keypirinha.load_icon(sources, force_reload, package_full_name)

### Description
Load an icon if it has not been loaded already and return a handle to it.

### Parameters
- **sources** (list or str) - Can be a string in case of a single source or a list of strings. This argument allows to specify one or several image files that are meant to represent the **same** icon, with different sizes.
- **force_reload** (bool, optional) - Whether to force reloading the icon.
- **package_full_name** (str, optional) - The full name of the package the icon belongs to.
```

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

### keypirinha.version_string()

Source: https://keypirinha.com/api/module.html

Returns the application's version as a dotted string (e.g., 'M.mm.pppp'). Prefer `version()` for version comparisons.

```APIDOC
## keypirinha.version_string()

### Description
Return application’s version in a dotted string as in `M.mm.pppp` where _M_ is the major version number, _m_ the minor version number, and _p_ is the patch revision. Prefer `version()` if the intent is to compare versions.

### Method
keypirinha.version_string()

### Parameters
None

### Returns
- **str**: The application version as a dotted string.

### Response Example
```json
"2.1.0"
```
```

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

### keypirinha.computer_name()

Source: https://keypirinha.com/api/module.html

Returns the computer's NetBIOS name.

```APIDOC
## keypirinha.computer_name()

### Description
Return computer’s NetBIOS name. This is the name used when looking for computer-specific configuration files.

### Method
`keypirinha.computer_name()`
```

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

### keypirinha.label()

Source: https://keypirinha.com/api/module.html

Returns the application’s display name.

```APIDOC
## keypirinha.label()

### Description
Return application’s display name (e.g.: `Keypirinha`).

### Method
`keypirinha.label()`
```

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

### Get Embedded Python Version

Source: https://keypirinha.com/api/python.html

Use `sys.version` to retrieve the exact version of the embedded Python interpreter within Keypirinha. This can also be found in the Console log.

```python
>>> import sys
>>> sys.version
'3.5.0 (default, Oct 18 2015, 16:49:14) [MSC v.1800 64 bit (AMD64)]'
```

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

### keypirinha_util.shell_known_folder_path

Source: https://keypirinha.com/api/module-util.html

Retrieves the path of a Shell Known Folder using its GUID. This function is recommended over direct OS calls as it handles platform differences and potential issues.

```APIDOC
## keypirinha_util.shell_known_folder_path(guid)

### Description
Returns the path of a Shell Known Folder according to its GUID. This function is recommended over direct OS calls as it handles platform differences and potential issues.

### Parameters
#### Path Parameters
- **guid** (str) - Required - The GUID of the desired Known Folder. Format must be: `{xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx}` (case-insensitive; the curly braces can be omited). The list of Known Folders is available on MSDN. Note that not all Known Folders are available on every platforms.

### Raises
- **ValueError** – The specified GUID is invalid (type, format or value). Or this Known Folder is not available on this platform. Or the specified Known Folder is virtual.
- **OSError** – The Known Folder is virtual, or not available on this platform.

### Note
Internally calls Win32’s `SHGetKnownFolderPath`.
```

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

### Get Keypirinha Process ID

Source: https://keypirinha.com/api/module.html

Use this function to retrieve the Process ID (PID) of the Keypirinha application's main process. It is preferred over `os.getpid()` for future compatibility.

```python
keypirinha.get_pid()
```

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

### keypirinha.version()

Source: https://keypirinha.com/api/module.html

Returns the application's version as a tuple of unsigned integers (major, minor, patch) suitable for version comparison.

```APIDOC
## keypirinha.version()

### Description
Return application’s version in a tuple of unsigned integers that can be used for comparison. Format is `(major, minor, patch)`.

### Method
keypirinha.version()

### Parameters
None

### Returns
- **tuple**: A tuple containing the major, minor, and patch version numbers.

### Example
```python
if keypirinha.version() > (2, ):
    print("Version is greater than v2")
if keypirinha.version() <= (1, 1):
    print("Version is less than or equal to v1.1")
```

### Response Example
```json
[2, 1, 0]
```
```

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

### Declare Extra Item for WebSuggest

Source: https://keypirinha.com/packages/websuggest.html

Example of declaring an additional item in Keypirinha's catalog that uses a suggestions provider. This snippet shows how to override default actions and provider-specific settings for a custom item.

```ini
[item/DuckDuckGo Autocomplete]
# Required: the name of a declared provider.
# It must reference a declared and enabled provider
# (i.e. ``[predefined_provider/*]`` or ``[provider/*]`` sections).
provider = duckduckgo

# Optional: override the default_action value from the [main] section.
# In this example, we use copy_result to simulate an "autocomplete"
# behavior.
default_action = copy_result

# Optional: enable/disable an item at runtime
# * A disabled item will not be inserted into the Catalog
# * Default: yes
enable = no

# Optionally, any setting of the underlying provider can be overridden
# specifically for this particular item. To do so, just redefine them here
# by prefixing their name with "provider." (without quotes).
#
# In other words, the "provider.*" values defined here only affect the
# initial definition of the "duckduckgo" provider for this particular item.
#
# For this example, we override the HTTP User-Agent value sent by Keypirinha
# to the DuckDuckGo API; we also ensure that the DuckDuckGo web interface
# provides search results in English.
provider.api_headers = User-Agent Keypirinha
provider.browse_args =
    q {terms}
    kl us-en


```

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

### Configure Keypirinha Portable Mode

Source: https://keypirinha.com/install.html

Use this `portable.ini` file to specify a custom directory for Keypirinha's configuration and local data files when running in Portable Mode. Ensure the specified directory exists and is writable. Environment variables are supported.

```ini
# Notes:
# * The specified directory must exist already when Keypirinha is started
#   and it must be readable and writable by Keypirinha
# * If the path is not absolute, it is assumed to be relative to
#   Keypirinha's directory
# * In this example, both sub-directories will be created automatically by
#   Keypirinha if needed:
#     C:\SomewhereUnderTheRainbow\KeypirinhaData\Profile
#     C:\SomewhereUnderTheRainbow\KeypirinhaData\Local
# * It does not have to be named KeypirinhaData
# * File must be encoded in UTF-8 (no BOM necessary)
# * Environment variables are expanded (e.g. %USERNAME%)
portable_dir = C:\SomewhereUnderTheRainbow\KeypirinhaData

```

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

### Define Custom Item Categories

Source: https://keypirinha.com/api/module.html

When creating items, use standard categories when possible. If a standard category does not fit, define custom category IDs starting from ItemCategory.USER_BASE + 1 to avoid collisions between plugins.

```python
MY_CUSTOM_ITEMCAT = keypirinha.ItemCategory.USER_BASE + 1
MY_SECOND_CUSTOM_ITEMCAT = keypirinha.ItemCategory.USER_BASE + 2
```

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

### build_urllib_opener

Source: https://keypirinha.com/api/module-net.html

Builds a urllib opener with support for custom proxy configurations and SSL settings.

```APIDOC
## build_urllib_opener

### Description
Builds a `urllib.request.OpenerDirector`-compatible opener object, allowing for custom proxy configurations and SSL hostname checking.

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
* **proxies** (_dict_) – A dictionary of proxies to pass to the constructor of `urllib.request.ProxyHandler`. Defaults to `None`, which uses system-level proxies. An empty dictionary `{}` means no proxy will be used.
* **extra_handlers** (_list_) – A list/tuple of extra handlers to append to the final handlers chain.
* **extra_pre_handlers** (_list_) – A list/tuple of extra handlers to prepend to the final handlers chain. Use with caution.
* **ssl_check_hostname** (_bool_) – Determines if the hostname should be checked against the received security certificate. Defaults to `None`, which follows `urllib`'s default behavior. If set to a boolean, it modifies the `HTTPSHandler` behavior.

### Request Example
```python
proxies = {'http': "http://proxy_user:proxy_pass@127.0.0.1:8080"}
opener = build_urllib_opener(proxies=proxies)
with opener.open("http://httpbin.org/ip") as response:
    print(response.read())
```

### Response
#### Success Response (200)
Returns a `urllib.request.OpenerDirector`-compatible opener object.

#### Response Example
(OpenerDirector object)

### Notes
* SOCKS proxy support is experimental and requires the PySocks module.
* DNS requests do not go through SOCKS proxies.
* IPv6 connections through SOCKS proxies are not supported.
* If SOCKS proxy is specified, it takes precedence over other proxy types.
```

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

### keypirinha_util.chardet_open

Source: https://keypirinha.com/api/module-util.html

Opens a file with automatic encoding detection. Skips detection if the mode includes 'b'. Uses the 'chardet' module.

```APIDOC
## keypirinha_util.chardet_open

### Description
An `open()` function that **tries** to detect text file’s encoding.
This function has the same return value, behavior and parameters than the standard `open()` function except that `encoding` argument is ignored. It may raise the same exceptions as well.

### Note
* Automatic encoding detection is skipped if the `b` flag is specified in the `mode` argument.
* The `chardet` module is used for the auto-detection.

### Parameters
* **file** (_file_) –
* **mode** (_str_) – Defaults to 'r'.
* **buffering** (_int_) – Defaults to -1.
* **encoding** (_str_) – Ignored.
* **kwargs** – Additional keyword arguments passed to the underlying `open()` function.
```

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

### UrllibOpener.open

Source: https://keypirinha.com/api/module-net.html

Overrides urllib.request.OpenerDirector.open to automatically apply Keypirinha's timeout settings.

```APIDOC
## UrllibOpener.open

### Description
Overrides `urllib.request.OpenerDirector.open()` in order to apply the `timeout` value automatically from Keypirinha’s settings. Forcing a _timeout_ value here is still allowed but discouraged.

### Method
`open`

### Endpoint
N/A (Method of UrllibOpener class)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
- **fullurl** (str) - The URL to open.
- **args** - Additional arguments.
- **data** (bytes, optional) - Data to send with the request.
- **timeout** (int or float, optional) - The timeout value for the request. Discouraged to force.
- **kwargs** - Additional keyword arguments.

### Request Example
```python
# Assuming 'opener' is an instance of UrllibOpener
with opener.open("http://example.com") as response:
    print(response.read())
```

### Response
#### Success Response (200)
Returns a response object similar to `urllib.request.urlopen`.

#### Response Example
```json
{
  "example": "response object"
}
```
```

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

### Plugin.warn()

Source: https://keypirinha.com/api/plugin.html

Logs a warning message to the Keypirinha console.

```APIDOC
## Plugin.warn(_* objects_, _sep =' '_)

### Description
Logs a warning message. The `objects` and `sep` arguments are handled similarly to the built-in `print()` function.

### Parameters
* **objects** (_*_) – The objects to log.
* **sep** (_str_, optional) – The separator between objects. Defaults to a space.

### See Also
`info()`, `err()`, `dbg()`
```

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

### keypirinha_util.shell_execute

Source: https://keypirinha.com/api/module-util.html

Executes, opens, or edits a file, directory, or application using the Win32 `ShellExecuteEx` function.

```APIDOC
## keypirinha_util.shell_execute

### Description
Executes, opens, or edits a file, directory, or application using the Win32 `ShellExecuteEx` function.

### Parameters
#### Path Parameters
- **thing** (str) - Required - The file, directory, or other item to execute/launch/edit.
- **args** (str) - Optional - Quoted arguments for the execution. A list of strings can also be provided.
- **working_dir** (str) - Optional - The directory to execute from. If empty, it's auto-detected.
- **verb** (str) - Optional - The action to perform (e.g., `open`, `edit`, `explore`).
- **try_runas** (bool) - Optional - If true, attempts to run with elevated permissions on access denied.
- **detect_nongui** (bool) - Optional - If true, detects console applications and uses the configured terminal.
- **api_flags** (int) - Optional - Flags to forward to `ShellExecuteEx`.
- **terminal_cmd** (str) - Optional - Forces a specific console emulator if `detect_nongui` is true.
- **show** (int) - Optional - Value for the `nShow` parameter of `ShellExecuteEx`. Defaults to `SW_SHOWNORMAL` if less than zero.

### Raises
- **FileNotFoundError** - If the `thing` was not found.
- **OSError** - If the specified `thing` is an unreadable link, `ShellExecuteEx` fails, or an internal error occurs.
```

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

### Configure FilesCatalog Profile

Source: https://keypirinha.com/packages/filescatalog.html

This configuration defines a catalog named 'Things' that activates automatically. It specifies directories to scan, including standard Windows folders and system directories, and applies filters to include only specific file extensions. The `file_item_label` is customized to display the catalog name, parent directory, and cleaned file name for better search results.

```ini
[profile/Things]
activate = yes
paths =
    C:\MyDocs
    C:\MyTools
    ${var:KNOWNFOLDER_DOWNLOADS}\**
    ${env:SYSTEMROOT}\system32\**
filters = + ext: .txt .xls .cmd .cpl
file_item_label = {profile}: {dir1}\{clean_name}

```

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

### Plugin Class Overview

Source: https://keypirinha.com/api/plugin.html

The Plugin class serves as the foundation for all third-party plugins. Only methods prefixed with 'on_' are called by the Keypirinha application.

```APIDOC
## class keypirinha.Plugin

Base class for third-party plugins.

Note
Methods prefixed with `on_` are the only ones called by the application.

`_debug` = False
    Flag to enable/disable output of `dbg()`.
    Warning
    Redistributed plugins must always have this flag disabled.

`__init__()`
    Plugin’s default constructor. When implementing a new plugin, it is good practice to call it:
    ```python
    def __init__(self):
        super().__init__()
    ```

`on_start()`
    This is the first method called by the application after a plugin has been instanciated.
    What should be done in this method:
      * Read configuration file(s)
      * Read state data from package’s cache, if any, that may be needed elsewhere in this plugin
      * Do any heavy, one-time, initialization (i.e. instead of doing it from `__init__` or even `on_catalog()` for example)

    See also
    See the Loading section for more information about the _plugin loading_ process. And Messages Workflow.

`on_catalog()`
    Plugin is requested to setup its catalog by calling either `set_catalog()` or `merge_catalog()`.
    Note
      * This method may be called at any time, and not necessarily at start-time.
      * Since this method may be called several times during instance’s lifetime, one-time initialization, if any, must always be done in `on_start()`.

    See also
    See the Loading section for more information about the _plugin loading_ process. And Messages Workflow.

`on_suggest(_user_input_ , _items_chain =[]_)`
    Called when the user is typing their search terms _or_ item’s arguments.
    When no item has been selected yet by the user, the _items_chain_ list is empty and _user_input_ is a string containing the initial search terms. In that case, this `SUGGEST` message has been broadcasted to every loaded plugin.
    Otherwise, this `SUGGEST` message has been sent to this plugin only and _items_chain_ is a non-empty list that contains one or more `CatalogItem` object(s) that belong to this plugin and _user_input_ is a string typed by the user that is meant to be the arguments of the lastly selected item (i.e. `items_chain[-1]`).
    More precisely, _items_chain_ contains the full history of the items that have been selected by the user during this search session, plugins usually only need to deal with the last and/or the first item(s) in the _items_chain_ list (i.e. `items_chain[-1]` and/or `items_chain[0]`; which may be equal).
    If the plugin implements this method, it is expected to set its **suggestions** catalog by using `set_suggestions()`. The list of suggestions may be empty.
    See also
    See the Messages Workflow section.

`on_execute(_catalog_item_ , _catalog_action =None_)`
    Called once the user has selected an item and wants to launch it, optionally using the passed action.
    _catalog_item_ is the selected `CatalogItem` object to execute, belonging to this plugin.
    _catalog_action_ is either `None` or a `CatalogAction` object; it might not have been created by this plugin though, in which case `keypirinha_util.execute_default_action()` may be of interest.
    See also
    See the Messages Workflow section.

`on_activated()`
    Called when the LaunchBox has been invoked by the user, either by typing the dedicated global hotkey, or by using the contextual menu of the application icon located in the system tray.
    Note
    The `ACTIVATED` message automatically discards any pending `DEACTIVATED` message in the queue. As a result, an `ACTIVATED` message is not always followed by a `DEACTIVATED` message. For example, if your plugin takes more time to process the `ACTIVATED` message than the end-user to perform her search **and** deactivate the window **and** then re-activate it, the plugin will receive a new `ACTIVATED` message without being notified about the `DEACTIVATED` event that occurred in between.
    See also
    `on_deactivated()`

`on_deactivated()`
    Called when the LaunchBox has been hidden. Either because an item has been executed for example, or because the user canceled her search.
    Note
    A `DEACTIVATED` message is not always preceded by an `ACTIVATED` message. See the note in `on_activated()` documentation for more information.
    See also
    `on_activated()`

`on_events(_flags_)`
    Called when some event(s) occurred.
    _flags_ can be one or several flags defined in `Events`.
    Note
    While Keypirinha tries to group flags at a given time in order to reduce the number of calls made to this method, calls are still made in a real-time fashion to ensure plugins get notified as soon as possible. In other words, there is no waiting mechanism involved to accumulate these flags and plugin developer should not expect flags to be always grouped.

`id()`
    Get the _id_ number (int) of this plugin.
    This _id_ uniquely identifies this plugin **during the current session only**.

`full_name()`
    Get the fully qualified name of this plugin.
    See also
    `friendly_name()`, `package_full_name()`

`name()`
    
```

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

### keypirinha.settings()

Source: https://keypirinha.com/api/module.html

Retrieves the Settings object associated with the Keypirinha application. This object provides access to application settings, which may be updated by the user at any time.

```APIDOC
## keypirinha.settings()

### Description
Return the `Settings` object associated with the application.

### Method
keypirinha.settings()

### Parameters
None

### Response
#### Success Response (Settings Object)
- Returns the application's `Settings` object.

### Response Example
```json
{
  "setting1": "value1",
  "setting2": "value2"
}
```
```
Tokens:
Raw