13.2.2. keypirinha_util module¶

The keypirinha_util module offers some utility features frequently required by the plugin developer.

13.2.2.1. Reference¶

class keypirinha_util.FileAttr(value)¶

Bases: enum.IntEnum

File attribute flags returned by file_attributes().

COMPRESSED = 524288¶: File is compressed.

DIR = 2¶: Path points to a directory.

ENCRYPTED = 1048576¶: File is encrypted.

EXE = 16¶: Path points to an executable. Combined with FILE.

EXE_CONSOLE = 32¶: Path points to an executable. Combined with FILE and EXE.

EXE_GUI = 64¶: Path points to an executable. Combined with FILE and EXE.

FILE = 4¶: Path points to a regular file.

HIDDEN = 262144¶: File is hidden.

LINK = 8¶: Path points to a link file (.lnk).

READONLY = 131072¶: File is read-only.

REMOVABLE = 4194304¶: File is a removable media or is stored on a removable media.

SHARED = 2097152¶: File is shared.

UNKNOWN_TYPE = 1¶: Path points to an existing item of an unknown type. This flag might be combined with other flags except DIR, FILE, LINK, EXE, EXE_CONSOLE and EXE_GUI.

class keypirinha_util.ScanFlags(value)¶

Bases: enum.IntEnum

The flags to pass to scan_directory().

ABORT_ON_ERROR = 16¶: Abort if any error occurs while scanning a sub-folder

CASE_SENSITIVE = 8¶: Case-sensitive scan (default is case-unsensitive)

DEFAULT = 3¶: Combination of SCAN_FILES | SCAN_DIRS

DIRS = 2¶: List directories

FILES = 1¶

everything that is not a directory)

Type: List files (i.e.

HIDDEN = 4¶: List hidden files

keypirinha_util.browse_directory(plugin, base_dir, check_base_dir=True, search_terms='', store_score=False, show_dirs_first=True, show_hidden_files=False, show_system_files=False)¶

Scan the first level of a directory according to a search term (optional) and some filtering rules in order to get keypirinha.CatalogItem objects to feed keypirinha.Plugin.set_suggestions().

Parameters

plugin (keypirinha.Plugin) – The parent plugin of the keypirinha.CatalogItem objects to be created. It may be used to print error/warning messages as well.
base_dir (str) – The path of the directory to browse.
check_base_dir (bool) – Print an error message if the directory does not exist and returns an keypirinha.ItemCategory.ERROR keypirinha.CatalogItem object in the result (the format of the returned tuple is unchanged).
search_terms (str) – If not empty, it will be fuzzy matched against the name of each found item (see fuzzy_score()). If the returned score is zero, the item is not included in the returned list. If the string is empty, items will be sorted by name using the natsort module.
store_score (bool) – If search_terms is not empty, the resulting score of the call to fuzzy_score() will be stored in the data_bag property of every inserted result item.
show_dirs_first (bool) – Indicates if directories should be pushed at the top of the resulting list.
show_hidden_files (bool) – Indicates if hidden items should included. Note that a hidden item can also be system.
show_system_files (bool) – Indicates if system items should included. Note that a system item can also be hidden.

Returns

A tuple of 3 elements (items, match_method, sort_method) where items is a list of keypirinha.CatalogItem objects, match_method is a keypirinha.Match value and sort_method is a keypirinha.Sort value.

Return type

tuple

keypirinha_util.chardet_open(file, mode='r', buffering=- 1, encoding=None, **kwargs)¶

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.

keypirinha_util.chardet_slurp(file)¶: Fully extract a text file into memory after having automatically detected its encoding.

keypirinha_util.cmdline_quote(arg_or_list, force_quote=False)¶

Joins and quotes arguments the Windows way.

Parameters

arg_or_list (list) – The list of arguments (strings) to join and quote. This arguments can also be a string, in which case it is handled as if it was a list with a single element.
force_quote (bool) – Force every arguments, even those that normally would not require to be quoted (i.e.: the ones with no white space included).

Returns

The resulting string (command line) containing the quoted arguments.

Return type

str

Raises

TypeError – At least one of the passed arguments has an unsupported type.

See also

cmdline_split() if you want to do the opposite (i.e.: to split a command line).

keypirinha_util.cmdline_split(cmdline)¶

Splits and unquotes (the Windows way) the given command line (string).

Returns: The split command line, a list of strings containing every argument.
Return type: list
Raises: OSError – The underlying call to Win32’s CommandLineToArgvW function failed.

See also

cmdline_quote() if you want to do the opposite (i.e.: to join and quote a list of arguments).

keypirinha_util.execute_default_action(plugin, catalog_item, catalog_action)¶: Executes a default keypirinha.CatalogAction using a given keypirinha.CatalogItem object. plugin is the calling keypirinha.Plugin object.

keypirinha_util.explore_file(file)¶

Open file explorer at a given location (file, which may also be a folder).

The file_explorer global setting is used if possible, otherwise Windows Explorer is invoked.

file may be empty or None in which case the file explorer is executed with no particular location specified.

keypirinha_util.file_attributes(file, follow_link=False)¶

Fetches and returns the attributes of a given file.

If the follow_link argument is True and file is a link, the function will return the attributes of its target; even if the target is also a link file (i.e.: only one level of recursion).

Returns: Combination of attributes.
Return type: FileAttr
Raises: FileNotFoundError – file is not found or not accessible. Or if the link could not be resolved (in case follow_link is True).

keypirinha_util.fuzzy_score(search, against, apply_same_case_bonus=False)¶

Returns the matching score of a search string against another one.

If case matters, the apply_same_case_bonus argument can be set to True to apply a bonus on a matching characters that have the same case. You usually do not want this though since it might feel quite unnatural to the end-user.

Returns: The score is an unsigned integer. 0 (zero) means no match, a value greater than zero means a match. The higher the score, the better the match is.
Return type: int

keypirinha_util.get_clipboard()¶

Returns a string containing system’s clipboard only if it contains text.

An empty string is returned otherwise.

See also

set_clipboard()

keypirinha_util.kwargs_decode(encoded_string)¶: Decodes a string encoded by kwargs_encode() and returns a dictionary.

See also

kwargs_encode()

keypirinha_util.kwargs_encode(**kwargs)¶

URL encodes passed keyword arguments into an escaped string that can be used as a target property for a keypirinha.CatalogItem object.

Only basic types are allowed: bool, int, float and str. Hint: use the unpack operator to pass a dictionary like in: kwargs_encode(**mydict)

Returns

The encoded string that can be decoded by kwargs_decode().

Return type

str

Raises

TypeError – The type of a passed value is invalid.
UnicodeEncodeError – urllib.parse.quote_plus() failed.

See also

kwargs_decode()

keypirinha_util.raise_winerror(winerr=None, msg=None)¶

Raises OSError (formerly WindowsError) using the given Windows Error number. If the error number is not given, ctypes.GetLastError() is called.

Does nothing if winerr, or by default, the result of ctypes.GetLastError(), is 0 (zero).

keypirinha_util.read_link(link_file)¶

Reads the properties of a Shell Link File (.lnk).

Parameters

link_file (str) – The path of the .lnk file.

Returns

A dict containing the properties:

{'target': "The resolved target file; path is already expanded",
    'params': "Target's parameters (may be None)",
    'expanded_params_list': ["split", "and", "expanded 'params'", "or empty list"],
    'working_dir': "Working directory (may be None)",
    'desc': "Description (may be None)",
    'show_cmd': "The 'show command' value (int; can be SW_SHOWNORMAL, SW_SHOWMAXIMIZED or SW_SHOWMINIMIZED; may be None)",
    'icon_location': "The icon location string that should be readable by shell_string_resource() (may be None)",
    'runas': "A boolean to indicate target should be run with elevated privileges",
    'flags': "The raw flags value read from IShellLink (int)",
    'is_msi': "A boolean flag equivalent to the (flags & SLDF_HAS_DARWINID) test"}

Return type

dict

Raises

IOError – The file could not be read or is not a link.

keypirinha_util.scan_directory(base_dir, name_patterns='*', flags=<ScanFlags.DEFAULT: 3>, max_level=0)¶

Walks a directory and builds a list of relative paths.

Warning

This function is only kept to maintain backward compatibility. It is recommended to use os.scandir() instead.
This function has been developed as a fast alternative to os.walk(). However since then, os.scandir() has been implemented and offers a more Pythonic way to scan a directory.

This function offers an alternative to os.walk() or the more recent os.scandir(), that has the ability to filter the elements to find by name and/or by type, and to define how deep the scan has to be done.

Parameters

base_dir (str) – The path to the directory to scan.
name_patterns (list) – Allows to apply one (a string can be passed) or several filters to the name of the found elements. Allowed wildcards are * (zero or several unknown characters) and ? (any character). If you only want to apply one filter, you may pass a string. Typical example: *.txt to list all the .txt files.
flags (ScanFlags) – One or a combination of flags to control scan’s behavior.
max_level (int) – Specifies how deep the scan should be. 0 (zero) means only the immediate content of the specified base_dir will be returned. A max_level of 1 will also include the immediate content of its sub-directories, and so on… Specify a value of -1 to walk the tree completely. The maximum theorical value is 0xffffffff. A negative value equals 0xffffffff.

Returns

The paths (strings) of found files and/or directories. Paths are relative to base_dir. The full path of an element can be build that way:

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

Return type

list

Raises

OSError – something went wrong while trying to open the specified base_dir or during the scan.

Note

Win32’s FindFirstFile is used internally.

Deprecated since version This: function is deprecated in favor of os.scandir(). It is kept here only to maintain backward compatibility.

keypirinha_util.set_clipboard(text)¶: Sets the content of system’s clipboard.

See also

get_clipboard()

keypirinha_util.shell_execute(thing, args='', working_dir='', verb='', try_runas=True, detect_nongui=True, api_flags=None, terminal_cmd=None, show=- 1)¶

Executes, opens, edits (or whatever) an application, a file, a directory, by calling Win32’s ShellExecuteEx function.

Parameters

thing (str) – The thing to execute/launch/edit/whatever. It can be a file, a directory, or anything recognized by ShellExecuteEx.
args (str) – The quoted arguments (optional). Note that a list of arguments (strings) can be given in which case cmdline_quote() is implicitely called.
working_dir (str) – The directory to execute from. This value can be empty, in which case this function tries to automatically detect it.
verb (str) – Specifies the action to be performed and is passed as-is to ShellExecuteEx. This value can be empty to request default action associated with the given thing. Here is the list of the common verbs from the Microsoft’s documentation: open, edit, explore, find, print and properties. Note that all verb are not available with all kind of thing.
try_runas (bool) – Automatically try to run with elevated permissions if the first call to ShellExecuteEx failed with ACCESS_DENIED error.
detect_nongui (bool) – Automatically detect if thing is a console application (or a link pointing to a console application). In that case, the terminal setting of the external section defined in the application’s configuration file will be used to launch thing.
api_flags (int) – If specified, those flags will be forwarded to ShellExecuteEx. The SEE_MASK_NOASYNC (0x100), SEE_MASK_FLAG_NO_UI (0x400) and SEE_MASK_INVOKEIDLIST (0xC) flags are passed if this argument is None. See ShellExecuteEx documentation from Microsoft for more info.
terminal_cmd (str) – If detect_nongui is True, this value allows to force the console emulator to use, instead of reading the terminal setting of the external section defined in the application’s configuration file. Note that, like for the args parameter, a list of arguments (strings) can be given in which case cmdline_quote() is implicitely called.
show (int) – Value directly forwarded to the nShow parameter of ShellExecuteEx. It must be one of the SW_ constants. If this value is less than zero, default will be applied (currently SW_SHOWNORMAL).

Raises

FileNotFoundError – The thing was not found.
OSError – Specified thing is a link that could not be read. Or ShellExecuteEx failed with the given thing and arguments. Or an unexpected/unknown error occurred internally.

Warning

It is highly recommended to use this function instead of the standard os.startfile() because the later internally calls the ShellExecute system function, which is obsolete, known to be bugged and behaves incorrectly in some cases.

Note

A successful call does not necessarily mean the item has effectively been launched/executed as expected, or that the launched process ended successfully.
This function tries to resolve shell links for the thing and the terminal_cmd arguments. Which also mean shortucts’ arguments will be prepended, if any, to the final list of arguments.

See also

web_browser_command(), which is the preferred function to open a URL since it takes care of applying user’s preferences.

keypirinha_util.shell_known_folder_path(guid)¶

Returns the path of a Shell Known Folder according to its GUID.

Parameters

guid (str) – 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.

keypirinha_util.shell_resolve_exe_path(path_or_name)¶

Tries to resolve path_or_name using environment PATH and PATHEXT variables.

path_or_name can be a path or just the name of the executable to find, in which case PATHEXT will be used to find a match in the directories listed in the PATH value.

Returns None if executable could not be found or if an error occurred.

keypirinha_util.shell_string_resource(resource_location)¶

Returns the content of a string resource from an external module (DLL) according to its location. Returns None if an error occurred.

Parameters: resource_location (str) – The location of the desired string. The expected format is normally “@<PE-path>,-<stringID>” but the underlying function tries to be as flexible as possible since a lot of applications and shell extensions do not strictly comply to Microsoft’s rules.

keypirinha_util.shell_url_scheme_to_command(url_scheme)¶

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

Parameters: url_scheme (str) – 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()

keypirinha_util.slurp_text_file(file)¶: Deprecated since version 2.5.3: Use chardet_slurp() instead

keypirinha_util.web_browser_command(private_mode=None, new_window=None, url=None, execute=False)¶

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

private_mode (bool) – 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) – 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) –
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.

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).
execute (bool) – Only taken into account if a url is specified. If this argument is True, the given url will be opened using shell_execute() and taking the private_mode and new_window arguments into account if possible. The return value is then a boolean, indicating whether or not the URL has been launched successfully.

Returns

list: If execute is False, returns a list of arguments that represent the command line to execute in order to launch the web web browser. In that case, url can be specified so the returned command line arguments list is ready to use. Otherwise, the returned list will contain a placeholder (%1) to indicate where to insert the URL to open. Returns None if no browser could be found.
bool: If execute is True and a url is specified, this function will try to open the URL and returns a boolean to indicate whether or not the launch request is successful.

Raises

TypeError – The given url argument is invalid.