Shortcuts Module Reference

New in version 0.0.2.

Control the macOS Shortcuts application using JXA-like syntax.

Classes:

`XAShortcut`(properties)	A class for managing and interacting with shortcuts.
`XAShortcutFolder`(properties)	A class for managing and interacting with folders of shortcuts.
`XAShortcutFolderList`(properties[, filter])	A wrapper around lists of shortcuts folders that employs fast enumeration techniques.
`XAShortcutList`(properties[, filter])	A wrapper around lists of shortcuts that employs fast enumeration techniques.
`XAShortcutsApplication`(properties)	A class for managing and interacting with Shortcuts.app.

class PyXA.apps.Shortcuts.XAShortcut(properties)[source]

Bases: XASBPrintable, XAClipboardCodable

A class for managing and interacting with shortcuts.

See also

XAShortcutsApplication

New in version 0.0.2.

Attributes:

`accepts_input`	Whether the shortcut accepts input data.
`action_count`	The number of actions in the shortcut.
`color`	The color of the short.
`folder`	The folder that contains the shortcut.
`icon`	The shortcut's icon.
`id`	The unique identifier for the shortcut.
`name`	The name of the shortcut.
`subtitle`	The shortcut's subtitle.

Methods:

`get_clipboard_representation`()	Gets a clipboard-codable representation of the shortcut.
`run`([input])	Runs the shortcut with the provided input.

property accepts_input: bool: Whether the shortcut accepts input data.

property action_count: int: The number of actions in the shortcut.

property color: XAColor: The color of the short.

property folder: XAShortcutFolder: The folder that contains the shortcut.

get_clipboard_representation() → list[str | NSImage][source]

Gets a clipboard-codable representation of the shortcut.

When the clipboard content is set to a shortcut, the shortcut’s name, subtitle, and icon are added to the clipboard.

Returns:: The shortcut’s name, subtitle, and icon
Return type:: list[Union[str, str, AppKit.NSImage]]

New in version 0.0.8.

property icon: XAImage: The shortcut’s icon.

property id: str: The unique identifier for the shortcut.

property name: str: The name of the shortcut.

run(input: Any | None = None) → Any[source]

Runs the shortcut with the provided input.

Parameters:: input (Any, optional) – The input to pass to the shortcut, defaults to None
Returns:: The value returned when the shortcut executes
Return type:: Any
Example 1:: Run a shortcut without inputs

>>> import PyXA
>>> app = PyXA.Application("Shortcuts")
>>> folder = app.folders().by_name("Dev Tools")
>>> shortcut = folder.shortcuts().by_name("Show IP Address")
>>> shortcut.run()

Example 2:: Run a shortcut with text input

>>> import PyXA
>>> app = PyXA.Application("Shortcuts")
>>> shortcut = app.shortcuts().by_name("Show Notification")
>>> shortcut.run("Testing 1 2 3...")

Example 3:: Run a shortcut with URL input

>>> import PyXA
>>> app = PyXA.Application("Shortcuts")
>>> safari = PyXA.Application("Safari")
>>> document = safari.document(0)
>>> shortcut = app.shortcuts().by_name("Save URL as PDF")
>>> shortcut.run(document.url)

New in version 0.0.2.

property subtitle: str: The shortcut’s subtitle.

class PyXA.apps.Shortcuts.XAShortcutFolder(properties)[source]

Bases: XAObject, XAClipboardCodable

A class for managing and interacting with folders of shortcuts.

See also

XAShortcutsApplication

New in version 0.0.2.

Methods:

`get_clipboard_representation`()	Gets a clipboard-codable representation of the folder.
`shortcuts`([filter])	Returns a list of shortcuts matching the given filter.

Attributes:

`id`	A unique identifier for the folder.
`name`	The name string for the folder.

get_clipboard_representation() → str[source]

Gets a clipboard-codable representation of the folder.

When the clipboard content is set to a shortcut folder, the folders’s name is added to the clipboard.

Returns:: The name of the folder
Return type:: str

New in version 0.0.8.

property id: str: A unique identifier for the folder.

property name: str: The name string for the folder.

shortcuts(filter: dict | None = None) → XAShortcutList[source]

Returns a list of shortcuts matching the given filter.

Example 1:: Get all shortcuts in a folder

>>> import PyXA
>>> app = PyXA.Application("Shortcuts")
>>> folder = app.folders()[0]
>>> print(folder.shortcuts())
<<class 'PyXA.apps.Shortcuts.XAShortcutList'>['Text Last Image', 'Shazam shortcut', 'Make QR Code', 'Music Quiz', ...]>

Example 2:: Get a list of shortcut colors in a folder

>>> import PyXA
>>> app = PyXA.Application("Shortcuts")
>>> folder = app.folders()[0]
>>> print(folder.shortcuts().color())
[<<class 'PyXA.XABase.XAColor'>r=0.21521323919296265, g=0.7715266942977905, b=0.32515448331832886, a=0.0>, <<class 'PyXA.XABase.XAColor'>r=0.2379034161567688, g=0.3681696951389313, b=0.7627069354057312, a=0.0>, ...]>

Changed in version 0.0.4: Now returns an object of XAShortcutList instead of a default list.

New in version 0.0.2.

class PyXA.apps.Shortcuts.XAShortcutFolderList(properties: dict, filter: dict | None = None)[source]

Bases: XAList, XAClipboardCodable

A wrapper around lists of shortcuts folders that employs fast enumeration techniques.

All properties of folders can be called as methods on the wrapped list, returning a list containing each folders’s value for the property.

New in version 0.0.4.

Methods:

`by_id`(id)
`by_name`(name)
`get_clipboard_representation`()	Gets a clipboard-codable representation of each folder in the list.
`id`()
`name`()
`shortcuts`([filter])

by_id(id: str) → XAShortcutFolder | None[source]

by_name(name: str) → XAShortcutFolder | None[source]

get_clipboard_representation() → list[str][source]

Gets a clipboard-codable representation of each folder in the list.

When the clipboard content is set to a list of shortcut folders, each folders’s name is added to the clipboard.

Returns:: The list of folder names
Return type:: list[str]

New in version 0.0.8.

id() → list[str][source]

name() → list[str][source]

shortcuts(filter: dict | None = None) → list[XAShortcutList][source]

class PyXA.apps.Shortcuts.XAShortcutList(properties: dict, filter: dict | None = None)[source]

Bases: XAList, XAClipboardCodable

A wrapper around lists of shortcuts that employs fast enumeration techniques.

All properties of shortcuts can be called as methods on the wrapped list, returning a list containing each shortcut’s value for the property.

New in version 0.0.4.

Methods:

`accepts_input`()
`action_count`()
`by_accepts_input`(accepts_input)
`by_action_count`(action_count)
`by_color`(color)
`by_folder`(folder)
`by_icon`(icon)
`by_id`(id)
`by_name`(name)
`by_subtitle`(subtitle)
`color`()
`folder`()
`get_clipboard_representation`()	Gets a clipboard-codable representation of each shortcut in the list.
`icon`()
`id`()
`name`()
`subtitle`()

accepts_input() → list[bool][source]

action_count() → list[int][source]

by_accepts_input(accepts_input: bool) → XAShortcut | None[source]

by_action_count(action_count: int) → XAShortcut | None[source]

by_color(color: XAColor) → XAShortcut | None[source]

by_folder(folder: XAShortcutFolder) → XAShortcut | None[source]

by_icon(icon: XAImage) → XAShortcut | None[source]

by_id(id: str) → XAShortcut | None[source]

by_name(name: str) → XAShortcut | None[source]

by_subtitle(subtitle: str) → XAShortcut | None[source]

color() → list[XAColor][source]

folder() → XAShortcutFolderList[source]

get_clipboard_representation() → list[list[str] | list[NSImage]][source]

Gets a clipboard-codable representation of each shortcut in the list.

When the clipboard content is set to a list of shortcuts, each shortcut’s name, subtitle, and icon are added to the clipboard.

Returns:: A list of each shortcut’s name, subtitle, and icon
Return type:: list[Union[list[str], list[str], list[AppKit.NSImage]]]

New in version 0.0.8.

icon() → XAImageList[source]

id() → list[str][source]

name() → list[str][source]

subtitle() → list[str][source]

class PyXA.apps.Shortcuts.XAShortcutsApplication(properties)[source]

Bases: XASBApplication, XACanOpenPath

A class for managing and interacting with Shortcuts.app.

New in version 0.0.2.

Classes:

ObjectType(value)

Types of objects that can be created using make().

Methods:

`folders`([filter])	Returns a list of folders matching the given filter.
`make`(specifier[, properties, data])	Creates a new element of the given specifier class without adding it to any list.
`run`(shortcut[, input])	Runs the shortcut with the provided input.
`shortcuts`([filter])	Returns a list of shortcuts matching the given filter.

Attributes:

`frontmost`	Whether Shortcuts is the active application.
`name`	The name of the application.
`version`	The version number of Shortcuts.app.

class ObjectType(value)[source]

Bases: Enum

Types of objects that can be created using make().

Attributes:

`FOLDER`
`SHORTCUT`

FOLDER = 'folder'

SHORTCUT = 'shortcut'

folders(filter: dict | None = None) → XAShortcutFolderList[source]

Returns a list of folders matching the given filter.

Example 1:: Get all folders

>>> import PyXA
>>> app = PyXA.Application("Shortcuts")
>>> print(app.folders())
<<class 'PyXA.apps.Shortcuts.XAShortcutFolderList'>['Starter Shortcuts', 'Window Management', 'Dev Tools', ...]>

Example 2:: Get the number of shortcuts contained in each folder

>>> import PyXA
>>> app = PyXA.Application("Shortcuts")
>>> all_shortcuts = app.folders().shortcuts()
>>> lengths = [len(ls) for ls in all_shortcuts]
>>> print(lengths)
[4, 3, 2, 15, 12, ...]

Changed in version 0.0.4: Now returns an object of XAShortcutFolderList instead of a default list.

New in version 0.0.2.

property frontmost: bool: Whether Shortcuts is the active application.

make(specifier: str | ObjectType, properties: dict | None = None, data: Any | None = None) → XAObject[source]

Creates a new element of the given specifier class without adding it to any list.

Use XABase.XAList.push() to push the element onto a list.

Parameters:

specifier (Union[str, XAShortcutsApplication.ObjectType]) – The classname of the object to create
properties (dict) – The properties to give the object
data (Any) – The data to give the object

Returns:

A PyXA wrapped form of the object

Return type:

XABase.XAObject

New in version 0.3.0.

property name: str: The name of the application.

run(shortcut: XAShortcut, input: Any | None = None) → Any[source]

Runs the shortcut with the provided input.

Parameters:

shortcut (XAShortcut) – The shortcut to run
input (Any, optional) – The input to pass to the shortcut, defaults to None

Returns:

The return value of the last action to execute

Return type:

Any

New in version 0.0.4.

shortcuts(filter: dict | None = None) → XAShortcutList[source]

Returns a list of shortcuts matching the given filter.

Example 1:: Get all shortcuts

>>> import PyXA
>>> app = PyXA.Application("Shortcuts")
>>> print(app.shortcuts())
<<class 'PyXA.apps.Shortcuts.XAShortcutList'>['Combine Screenshots & Share', 'Travel plans', 'Paywall Bypasser via Facebook', 'Display Notification', 'Text Converter For iMessage', ...]>

Changed in version 0.0.4: Now returns an object of XAShortcutList instead of a default list.

New in version 0.0.2.

property version: str: The version number of Shortcuts.app.