XABase Module

New in version 0.0.1.

General classes and methods applicable to any PyXA object.

Classes:

`AppleScript`([script])	A class for constructing and executing AppleScript scripts.
`Application`(app_name)	A wrapper around a macOS application providing access to its scripting functionality.
`XAAlias`(properties)	An alias in the file system.
`XAAliasList`(properties[, filter])	A wrapper around lists of aliases that employs fast enumeration techniques.
`XAApplication`(properties)	A general application class for both officially scriptable and non-scriptable applications.
`XAApplicationList`(properties[, filter])	A wrapper around a list of applications.
`XAApplicationPicker`([title, prompt, ...])	An application selection window.
`XAAttachment`(properties)	A class for managing and interacting with attachments in text documents.
`XAAttachmentList`(properties[, filter])	A wrapper around lists of text attachments that employs fast enumeration techniques.
`XAAttributeRun`(properties)	A class for managing and interacting with attribute runs in text documents.
`XAAttributeRunList`(properties[, filter])	A wrapper around lists of attribute runs that employs fast enumeration techniques.
`XACharacter`(properties)	A class for managing and interacting with characters in text documents.
`XACharacterList`(properties[, filter])	A wrapper around lists of characters that employs fast enumeration techniques.
`XAClassicDomainObject`(properties)	The Classic domain in the file system.
`XAClipboard`()	A wrapper class for managing and interacting with the system clipboard.
`XAColor`(*args)
`XAColorList`(properties[, filter])	A wrapper around lists of colors that employs fast enumeration techniques.
`XAColorPicker`([style])	A class for creating and interacting with a color picker window.
`XAColorPickerStyle`(value)	Options for which tab a color picker should display when first opened.
`XADialog`([text, title, buttons, ...])	A custom dialog window.
`XADisk`(properties)	A disk in the file system.
`XADiskItem`(properties)	An item stored in the file system.
`XADiskItemList`(properties[, filter, ...])	A wrapper around lists of disk items that employs fast enumeration techniques.
`XADiskList`(properties[, filter])	A wrapper around lists of disks that employs fast enumeration techniques.
`XADomain`(properties)	A domain in the file system.
`XADomainList`(properties[, filter])	A wrapper around lists of domains that employs fast enumeration techniques.
`XAEventsApplication`()	A base class for the System and Image events applications.
`XAFile`(properties)	A file in the file system.
`XAFileList`(properties[, filter, object_class])	A wrapper around lists of files that employs fast enumeration techniques.
`XAFileNameDialog`([prompt, default_name, ...])	A file name input window.
`XAFilePackage`(properties)	A file package in the file system.
`XAFilePackageList`(properties[, filter])	A wrapper around lists of file packages that employs fast enumeration techniques.
`XAFilePicker`([prompt, types, ...])	A file selection window.
`XAFolder`(properties)	A folder in the file system.
`XAFolderList`(properties[, filter])	A wrapper around lists of folders that employs fast enumeration techniques.
`XAFolderPicker`([prompt, default_location, ...])	A folder selection window.
`XAImage`([image_reference])	A wrapper around NSImage with specialized automation methods.
`XAImageList`(properties[, filter, obj_class])	A wrapper around lists of images that employs fast enumeration techniques.
`XAList`(properties[, object_class, filter])	A wrapper around NSArray and NSMutableArray objects enabling fast enumeration and lazy evaluation of Objective-C objects.
`XALocalDomainObject`(properties)	The local domain in the file system.
`XALocation`([raw_value, title, latitude, ...])	A location with a latitude and longitude, along with other data.
`XAMenu`(menu_items[, title, prompt, ...])	A custom list item selection menu.
`XANetworkDomainObject`(properties)	The network domain in the file system.
`XAObject`([properties])	A general class for PyXA scripting objects.
`XAParagraph`(properties)	A class for managing and interacting with paragraphs in text documents.
`XAParagraphList`(properties[, filter])	A wrapper around lists of paragraphs that employs fast enumeration techniques.
`XAPath`(path)	A path to a file on the disk.
`XAPredicate`()	A predicate used to filter arrays.
`XASentence`(properties)	A class for managing and interacting with sentences in text documents.
`XASentenceList`(properties[, filter])	A wrapper around lists of sentences that employs fast enumeration techniques.
`XASound`(sound_reference)	A class for playing and interacting with audio files and data.
`XASoundList`(properties[, filter])	A wrapper around lists of sounds that employs fast enumeration techniques.
`XASpotlight`(*query)	A Spotlight query for files on the disk.
`XASystemDomainObject`(properties)	The system domain in the file system.
`XAText`(properties)	A class for managing and interacting with the text of documents.
`XATextDocument`(properties)	A class for managing and interacting with text documents.
`XATextDocumentList`(properties[, filter, ...])	A wrapper around lists of text documents that employs fast enumeration techniques.
`XATextList`(properties[, filter, obj_class])	A wrapper around lists of text objects that employs fast enumeration techniques.
`XAURL`(url)	A URL using any scheme recognized by the system.
`XAURLList`(properties[, filter])	A list of URLs.
`XAUserDomainObject`(properties)	The user domain in the file system.
`XAVideo`(video_reference)	A class for interacting with video files and data.
`XAWord`(properties)	A class for managing and interacting with words in text documents.
`XAWordList`(properties[, filter])	A wrapper around lists of words that employs fast enumeration techniques.

Functions:

`OSType`(s)
`active_browser`()	Retrieves a PyXA representation of the most recently active browser application.
`camelize`(text)	Converts a string to camel case.
`current_application`()	Retrieves a PyXA representation of the frontmost application.
`running_applications`([unique])	Gets PyXA references to all currently visible (not hidden or minimized) running applications whose app bundles are stored in typical application directories.
`snakify`(text)	Converts a string to snake case.
`unOSType`(i)

Data:

`SUPPORTED_BROWSERS`	Browsers supported by PyXA, i.e. having dedicated PyXA Application classes.
`VERSION`	The installed version of PyXA
`supported_applications`	A list of names of supported scriptable applications

class PyXA.XABase.AppleScript(script: str | list[str] | None = None)[source]

Bases: object

A class for constructing and executing AppleScript scripts.

New in version 0.0.5.

Attributes:

`__dict__`
`__module__`
`__weakref__`	list of weak references to the object (if defined)
`file_path`	The file path of this script, if one exists
`last_result`	The return value of the last execution of the script
`script`	The lines of AppleScript code contained in the script

Methods:

`__init__`([script])	Creates a new AppleScript object.
`__repr__`()	Return repr(self).
`add`(script)	Adds the supplied string, list of strings, or script as a new line entry in the script.
`insert`(index, script)	Inserts the supplied string, list of strings, or script as a line entry in the script starting at the given line index.
`load`()	Loads an AppleScript (.scpt) file as a runnable AppleScript object.
`parse_result_data`()	Extracts string data from an AppleScript execution result dictionary.
`pop`([index])	Removes the line at the given index from the script.
`run`([args, dry_run])	Compiles and runs the script, returning the result.
`save`([path])	Saves the script to the specified file path, or to the path from which the script was loaded.

__annotations__ = {'file_path': 'XAPath', 'last_result': 'Any', 'script': 'list[str]'}

__dict__ = mappingproxy({'__module__': 'PyXA.XABase', '__doc__': 'A class for constructing and executing AppleScript scripts.\n\n .. versionadded:: 0.0.5\n ', '__init__': <function AppleScript.__init__>, 'last_result': <property object>, 'file_path': <property object>, 'add': <function AppleScript.add>, 'insert': <function AppleScript.insert>, 'pop': <function AppleScript.pop>, 'load': <function AppleScript.load>, 'save': <function AppleScript.save>, 'parse_result_data': <function AppleScript.parse_result_data>, 'run': <function AppleScript.run>, '__repr__': <function AppleScript.__repr__>, '__dict__': <attribute '__dict__' of 'AppleScript' objects>, '__weakref__': <attribute '__weakref__' of 'AppleScript' objects>, '__annotations__': {'script': 'list[str]', 'last_result': 'Any', 'file_path': 'XAPath'}})

__init__(script: str | list[str] | None = None)[source]

Creates a new AppleScript object.

Parameters:: script (Union[str, list[str], None], optional) – A string or list of strings representing lines of AppleScript code, or the path to a script plaintext file, defaults to None

New in version 0.0.5.

__module__ = 'PyXA.XABase'

__repr__()[source]: Return repr(self).

__weakref__: list of weak references to the object (if defined)

add(script: str | list[str] | AppleScript)[source]

Adds the supplied string, list of strings, or script as a new line entry in the script.

Parameters:: script (Union[str, list[str], AppleScript]) – The script to append to the current script string.
Example:

>>> import PyXA
>>> script = PyXA.AppleScript("tell application "Safari"")
>>> script.add("print the document of window 1")
>>> script.add("end tell")
>>> script.run()

New in version 0.0.5.

property file_path: XAPath: The file path of this script, if one exists

insert(index: int, script: str | list[str] | AppleScript)[source]

Inserts the supplied string, list of strings, or script as a line entry in the script starting at the given line index.

Parameters:

index (int) – The line index to begin insertion at
script (Union[str, list[str], AppleScript]) – The script to insert into the current script

Example:

>>> import PyXA
>>> script = PyXA.AppleScript.load("/Users/exampleUser/Downloads/Test.scpt")
>>> script.insert(1, "activate")
>>> script.run()

New in version 0.0.9.

property last_result: Any: The return value of the last execution of the script

load() → AppleScript[source]

Loads an AppleScript (.scpt) file as a runnable AppleScript object.

Parameters:: path (Union[XAPath, str]) – The path of the .scpt file to load
Returns:: The newly loaded AppleScript object
Return type:: AppleScript
Example 1:: Load and run a script

>>> import PyXA
>>> script = PyXA.AppleScript.load("/Users/exampleUser/Downloads/Test.scpt")
>>> print(script.run())
{
    'string': None,
    'int': 0,
    'bool': False,
    'float': 0.0,
    'date': None,
    'file_url': None,
    'type_code': 845507684,
    'data': {length = 8962, bytes = 0x646c6532 00000000 6c697374 000022f2 ... 6e756c6c 00000000 },
    'event': <NSAppleEventDescriptor: [ 'obj '{ ... } ]>
}

Example 2:: Load, modify, and run a script

>>> import PyXA
>>> script = PyXA.AppleScript.load("/Users/exampleUser/Downloads/Test.scpt")
>>> script.pop(1)
>>> script.insert(1, "activate")
>>> script.run()

New in version 0.0.8.

parse_result_data() → list[tuple[str, str]][source]

Extracts string data from an AppleScript execution result dictionary.

Parameters:: result (dict) – The execution result dictionary to extract data from
Returns:: A list of responses contained in the result structured as tuples
Return type:: list[tuple[str, str]]
Example:

>>> import PyXA
>>> script = PyXA.AppleScript.load("/Users/exampleUser/Downloads/Test.scpt")
>>> print(script.script)
>>> result = script.run()
>>> print(PyXA.AppleScript.parse_result_data(result))
['tell application "Messages"', '\tget chats', 'end tell']
[('ID', 'iMessage;-;+12345678910'), ('ID', 'iMessage;-;+12345678911'), ('ID', 'iMessage;-;example@icloud.com'), ...]

New in version 0.0.9.

pop(index: int = -1) → str[source]

Removes the line at the given index from the script.

Parameters:: index (int) – The index of the line to remove
Returns:: The text of the removed line
Return type:: str
Example:

>>> import PyXA
>>> script = PyXA.AppleScript.load("/Users/exampleUser/Downloads/Test.scpt")
>>> print(script.pop(1))
    get chats

New in version 0.0.9.

run(args: list | None = None, dry_run=False) → Any[source]

Compiles and runs the script, returning the result.

Parameters:

args (list, optional) – A list of arguments to pass to the script, defaults to None
dry_run (bool, optional) – Whether to compile and check the script without running it, defaults to False

Returns:

The return value of the script.

Return type:

Any

Example 1:

Basic Script Execution

>>> import PyXA
>>> script = PyXA.AppleScript(f"""tell application "System Events"
>>>     return 1 + 2
>>> end tell
>>> """)
>>> print(script.run())
{
    'string': '3',
    'int': 3,
    'bool': False,
    'float': 3.0,
    'date': None,
    'file_url': None,
    'type_code': 3,
    'data': {length = 4, bytes = 0x03000000},
    'event': <NSAppleEventDescriptor: 3>
}

Example 2:: Run Script With Arguments

>>> import PyXA
>>> script = PyXA.AppleScript(f"""on run argv
>>>     set x to item 1 of argv
>>>     set y to item 2 of argv
>>>     return x + y
>>> end run""")
>>> print(script.run([5, 6]))
{'
    string': '11',
    'int': 11,
    'bool': False,
    'float': 11.0,
    'date': None,
    'file_url': None,
    'type_code': 11,
    'data': {length = 4, bytes = 0x0b000000},
    'event': <NSAppleEventDescriptor: 11>
}

New in version 0.0.5.

save(path: XAPath | str | None = None)[source]

Saves the script to the specified file path, or to the path from which the script was loaded.

Parameters:: path (Union[XAPath, str, None], optional) – The path to save the script at, defaults to None
Example 1:: Save the script to a specified path

>>> import PyXA
>>> script = PyXA.AppleScript(f"""
>>>     tell application "Safari"
>>>         activate
>>>     end tell
>>> """)
>>> script.save("/Users/exampleUser/Downloads/Example.scpt")

Example 2:: Load a script, modify it, then save it

>>> import PyXA
>>> script = PyXA.AppleScript.load("/Users/steven/Downloads/Example.scpt")
>>> script.insert(2, "delay 2")
>>> script.insert(3, "set the miniaturized of window 1 to true")
>>> script.save()

New in version 0.0.9.

script: list[str]: The lines of AppleScript code contained in the script

class PyXA.XABase.Application(app_name: str)[source]

Bases: XAObject

A wrapper around a macOS application providing access to its scripting functionality.

Changed in version 0.1.1: Moved into the XABase module.

New in version 0.1.0.

Attributes:

`__annotations__`
`__module__`
`app_paths`	A list containing the path to each application

Methods:

__init__(app_name)

Creates a new application object.

__annotations__ = {'app_paths': list[str]}

__init__(app_name: str)[source]

Creates a new application object.

Parameters:: app_name (str) – The name of the target application

New in version 0.1.0.

__module__ = 'PyXA.XABase'

app_paths: list[str] = []: A list containing the path to each application

PyXA.XABase.OSType(s: str)[source]

PyXA.XABase.SUPPORTED_BROWSERS = ['Safari', 'Google Chrome', 'Google Chrome Canary', 'Google Chrome Beta', 'Google Chrome Dev', 'Chromium', 'Brave Browser', 'Brave Browser Dev', 'Brave Browser Beta', 'Brave Browser Nightly', 'Microsoft Edge', 'Microsoft Edge Beta', 'Microsoft Edge Dev', 'Microsoft Edge Canary', 'Opera', 'Opera Beta', 'Opera Developer', 'Opera GX', 'Opera Neon', 'Vivaldi', 'Blisk', 'Iridium', 'Yandex', 'Maxthon', 'Maxthon Beta', 'Arc', 'OmniWeb']: Browsers supported by PyXA, i.e. having dedicated PyXA Application classes.

PyXA.XABase.VERSION = '0.3.0': The installed version of PyXA

class PyXA.XABase.XAAlias(properties)[source]

Bases: XADiskItem

An alias in the file system.

New in version 0.1.0.

Attributes:

`__annotations__`
`__module__`
`creator_type`	The OSType identifying the application that created the alias.
`default_application`	The application that will launch if the alias is opened.
`file_type`	The OSType identifying the type of data contained in the alias.
`kind`	The kind of alias, as shown in Finder.
`product_version`	The version of the product (visible at the top of the "Get Info" window).
`short_version`	The short version of the application bundle referenced by the alias.
`stationery`	Whether the alias is a stationery pad.
`type_identifier`	The type identifier of the alias.
`version`	The version of the application bundle referenced by the alias (visible at the bottom of the "Get Info" window).

Methods:

`__init__`(properties)	Instantiates a PyXA scripting object.
`aliases`([filter])	Returns a list of aliases, as PyXA objects, matching the given filter.
`disk_items`([filter])	Returns a list of disk items, as PyXA objects, matching the given filter.
`file_packages`([filter])	Returns a list of file packages, as PyXA objects, matching the given filter.
`files`([filter])	Returns a list of files, as PyXA objects, matching the given filter.
`folders`([filter])	Returns a list of folders, as PyXA objects, matching the given filter.

__annotations__ = {}

__init__(properties)[source]

Instantiates a PyXA scripting object.

Parameters:: properties (dict, optional) – A dictionary of properties to assign to this object.

Changed in version 0.0.3: Removed on-the-fly creation of class attributes. All objects should concretely define their properties.

New in version 0.0.1.

__module__ = 'PyXA.XABase'

aliases(filter: dict | None = None) → XAAliasList[source]: Returns a list of aliases, as PyXA objects, matching the given filter.

New in version 0.1.0.

property creator_type: str: The OSType identifying the application that created the alias.

New in version 0.1.0.

property default_application: XADiskItem: The application that will launch if the alias is opened.

New in version 0.1.0.

disk_items(filter: dict | None = None) → XADiskItemList[source]: Returns a list of disk items, as PyXA objects, matching the given filter.

New in version 0.1.0.

file_packages(filter: dict | None = None) → XAFilePackageList[source]: Returns a list of file packages, as PyXA objects, matching the given filter.

New in version 0.1.0.

property file_type: str: The OSType identifying the type of data contained in the alias.

New in version 0.1.0.

files(filter: dict | None = None) → XAFileList[source]: Returns a list of files, as PyXA objects, matching the given filter.

New in version 0.1.0.

folders(filter: dict | None = None) → XAFolderList[source]: Returns a list of folders, as PyXA objects, matching the given filter.

New in version 0.1.0.

property kind: str: The kind of alias, as shown in Finder.

New in version 0.1.0.

property product_version: str: The version of the product (visible at the top of the “Get Info” window).

New in version 0.1.0.

property short_version: str: The short version of the application bundle referenced by the alias.

New in version 0.1.0.

property stationery: bool: Whether the alias is a stationery pad.

New in version 0.1.0.

property type_identifier: str: The type identifier of the alias.

New in version 0.1.0.

property version: str: The version of the application bundle referenced by the alias (visible at the bottom of the “Get Info” window).

New in version 0.1.0.

class PyXA.XABase.XAAliasList(properties: dict, filter: dict | None = None)[source]

Bases: XADiskItemList

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

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

New in version 0.1.0.

Attributes:

`__annotations__`
`__module__`

Methods:

`__init__`(properties[, filter])	Creates an efficient wrapper object around a list of scriptable elements.
`by_creator_type`(creator_type)
`by_default_application`(default_application)
`by_file_type`(file_type)
`by_kind`(kind)
`by_product_version`(product_version)
`by_short_version`(short_version)
`by_stationery`(stationery)
`by_type_identifier`(type_identifier)
`by_version`(version)
`creator_type`()
`default_application`()
`file_type`()
`kind`()
`product_version`()
`short_version`()
`stationery`()
`type_identifier`()
`version`()

__annotations__ = {}

__init__(properties: dict, filter: dict | None = None)[source]

Creates an efficient wrapper object around a list of scriptable elements.

Parameters:

properties (dict) – PyXA properties passed to this object for utility purposes
object_class (type, optional) – _description_, defaults to None
filter (Union[dict, None], optional) – A dictionary of properties and values to filter items by, defaults to None

Changed in version 0.0.8: The filter property is deprecated and will be removed in a future version. Use the filter() method instead.

New in version 0.0.3.

__module__ = 'PyXA.XABase'

by_creator_type(creator_type: str) → XAAlias | None[source]

by_default_application(default_application: XADiskItem) → XAAlias | None[source]

by_file_type(file_type: str) → XAAlias | None[source]

by_kind(kind: str) → XAAlias | None[source]

by_product_version(product_version: str) → XAAlias | None[source]

by_short_version(short_version: str) → XAAlias | None[source]

by_stationery(stationery: bool) → XAAlias | None[source]

by_type_identifier(type_identifier: str) → XAAlias | None[source]

by_version(version: str) → XAAlias | None[source]

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

default_application() → XADiskItemList[source]

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

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

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

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

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

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

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

class PyXA.XABase.XAApplication(properties)[source]

Bases: XAObject, XAClipboardCodable

A general application class for both officially scriptable and non-scriptable applications.

New in version 0.0.1.

Attributes:

`__annotations__`
`__module__`
`bundle_identifier`	The bundle identifier for the application.
`bundle_url`	The file URL of the application bundle.
`executable_url`	The file URL of the application's executable.
`front_window`	The frontmost window of the application.
`frontmost`	Whether the application is the active application.
`icon`	The application's icon.
`launch_date`	The date and time that the application was launched.
`localized_name`	The application's name.
`owns_menu_bar`	Whether the application owns the top menu bar.
`process_identifier`	The process identifier for the application instance.
`xa_apsc`
`xa_prcs`

Methods:

`__getattr__`(attr)
`__init__`(properties)	Instantiates a PyXA scripting object.
`activate`()	Activates the application, bringing its window(s) to the front and launching the application beforehand if necessary.
`focus`()	Hides the windows of all applications except this one.
`get_clipboard_representation`()	Gets a clipboard-codable representation of the application.
`hide`()	Hides all windows of the application.
`launch`()	Launches the application.
`menu_bars`([filter])
`quit`()	Quits the application.
`terminate`()	Quits the application.
`unfocus`()	Unhides (reveals) the windows of all other applications, but does not activate them.
`unhide`()	Unhides (reveals) all windows of the application, but does not does not activate them.
`windows`([filter])

__annotations__ = {}

__getattr__(attr)[source]

__init__(properties)[source]

Instantiates a PyXA scripting object.

Parameters:: properties (dict, optional) – A dictionary of properties to assign to this object.

Changed in version 0.0.3: Removed on-the-fly creation of class attributes. All objects should concretely define their properties.

New in version 0.0.1.

__module__ = 'PyXA.XABase'

activate() → XAApplication[source]

Activates the application, bringing its window(s) to the front and launching the application beforehand if necessary.

Returns:: A reference to the PyXA application object.
Return type:: XAApplication

See also

terminate(), unhide(), focus()

New in version 0.0.1.

property bundle_identifier: str: The bundle identifier for the application.

New in version 0.0.1.

property bundle_url: str: The file URL of the application bundle.

New in version 0.0.1.

property executable_url: str: The file URL of the application’s executable.

New in version 0.0.1.

focus() → XAApplication[source]

Hides the windows of all applications except this one.

Returns:: A reference to the PyXA application object.
Return type:: XAApplication
Example:

>>> import PyXA
>>> safari = PyXA.Application("Safari")
>>> safari.focus()

See also

unfocus()

New in version 0.0.1.

property front_window: XAObject: The frontmost window of the application.

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

New in version 0.0.1.

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

Gets a clipboard-codable representation of the application.

When the clipboard content is set to an application, three items are placed on the clipboard: 1. The application’s name 2. The URL to the application bundle 3. The application icon

After copying an application to the clipboard, pasting will have the following effects: - In Finder: Paste a copy of the application bundle in the current directory - In Terminal: Paste the name of the application followed by the path to the application - In iWork: Paste the application name - In Safari: Paste the application name - In Notes: Attach a copy of the application bundle to the active note The pasted content may be different for other applications.

Returns:: The clipboard-codable representation
Return type:: list[Union[str, AppKit.NSURL, AppKit.NSImage]]

New in version 0.0.8.

hide() → XAApplication[source]

Hides all windows of the application.

Returns:: A reference to the PyXA application object.
Return type:: XAApplication
Example:

>>> import PyXA
>>> safari = PyXA.Application("Safari")
>>> safari.hide()

See also

unhide()

New in version 0.0.1.

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

New in version 0.1.1.

launch() → XAApplication[source]

Launches the application.

Returns:: The application object.
Return type:: XAApplication

New in version 0.1.1.

property launch_date: datetime: The date and time that the application was launched.

New in version 0.0.1.

property localized_name: str: The application’s name.

New in version 0.0.1.

menu_bars(filter: dict | None = None) → XAList[source]

property owns_menu_bar: bool: Whether the application owns the top menu bar.

New in version 0.0.1.

property process_identifier: str: The process identifier for the application instance.

New in version 0.0.1.

quit() → XAApplication[source]

Quits the application. Synonymous with terminate().

Returns:: A reference to the PyXA application object.
Return type:: XAApplication
Example:

>>> import PyXA
>>> safari = PyXA.Application("Safari")
>>> safari.quit()

See also

terminate(), activate()

New in version 0.0.1.

terminate() → XAApplication[source]

Quits the application. Synonymous with quit().

Returns:: A reference to the PyXA application object.
Return type:: XAApplication
Example:

>>> import PyXA
>>> safari = PyXA.Application("Safari")
>>> safari.terminate()

See also

quit(), activate()

New in version 0.0.1.

unfocus() → XAApplication[source]

Unhides (reveals) the windows of all other applications, but does not activate them.

Returns:: A reference to the PyXA application object.
Return type:: XAApplication
Example:

>>> import PyXA
>>> safari = PyXA.Application("Safari")
>>> safari.unfocus()

See also

focus()

New in version 0.0.1.

unhide() → XAApplication[source]

Unhides (reveals) all windows of the application, but does not does not activate them.

Returns:: A reference to the PyXA application object.
Return type:: XAApplication
Example:

>>> import PyXA
>>> safari = PyXA.Application("Safari")
>>> safari.unhide()

See also

hide()

New in version 0.0.1.

windows(filter: dict | None = None) → XAList[source]

property xa_apsc

property xa_prcs

class PyXA.XABase.XAApplicationList(properties: dict, filter: dict | None = None)[source]

Bases: XAList

A wrapper around a list of applications.

New in version 0.0.5.

Attributes:

`__annotations__`
`__module__`

Methods:

`__contains__`(item)
`__getitem__`(key)	Retrieves the wrapped application object(s) at the specified key.
`__init__`(properties[, filter])	Creates an efficient wrapper object around a list of scriptable elements.
`__iter__`()
`__repr__`()	Return repr(self).
`bundle_identifier`()
`bundle_url`()
`by_bundle_identifier`(bundle_identifier)
`by_bundle_url`(bundle_url)
`by_executable_url`(executable_url)
`by_launch_date`(launch_date)
`by_localized_name`(localized_name)
`by_process_identifier`(process_identifier)
`executable_url`()
`first`()	Retrieves the first element of the list as a wrapped PyXA application object.
`hide`()	Hides all applications in the list.
`last`()	Retrieves the last element of the list as a wrapped PyXA application object.
`launch_date`()
`localized_name`()
`pop`([index])	Removes the application at the specified index from the list and returns it.
`process_identifier`()
`quit`()	Quits (terminates) all applications in the list.
`terminate`()	Quits (terminates) all applications in the list.
`unhide`()	Unhides all applications in the list.
`windows`()	Retrieves a list of every window belonging to each application in the list.

__annotations__ = {}

__contains__(item)[source]

__getitem__(key: int | slice)[source]: Retrieves the wrapped application object(s) at the specified key.

__init__(properties: dict, filter: dict | None = None)[source]

Creates an efficient wrapper object around a list of scriptable elements.

Parameters:

properties (dict) – PyXA properties passed to this object for utility purposes
object_class (type, optional) – _description_, defaults to None
filter (Union[dict, None], optional) – A dictionary of properties and values to filter items by, defaults to None

Changed in version 0.0.8: The filter property is deprecated and will be removed in a future version. Use the filter() method instead.

New in version 0.0.3.

__iter__()[source]

__module__ = 'PyXA.XABase'

__repr__()[source]: Return repr(self).

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

bundle_url() → list[XAURL][source]

by_bundle_identifier(bundle_identifier: str) → XAApplication | None[source]

by_bundle_url(bundle_url: XAURL | str) → XAApplication | None[source]

by_executable_url(executable_url: XAURL | str) → XAApplication | None[source]

by_launch_date(launch_date: datetime) → XAApplication | None[source]

by_localized_name(localized_name: str) → XAApplication | None[source]

by_process_identifier(process_identifier: str) → XAApplication | None[source]

executable_url() → list[XAURL][source]

first() → XAObject[source]

Retrieves the first element of the list as a wrapped PyXA application object.

Returns:: The wrapped object
Return type:: XAObject

New in version 0.0.5.

hide()[source]

Hides all applications in the list.

Example 1:: Hide all visible running applications

>>> import PyXA
>>> apps = PyXA.running_applications()
>>> apps.hide()

See also

unhide()

New in version 0.0.5.

last() → XAObject[source]

Retrieves the last element of the list as a wrapped PyXA application object.

Returns:: The wrapped object
Return type:: XAObject

New in version 0.0.5.

launch_date() → list[datetime][source]

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

pop(index: int = -1) → XAObject[source]: Removes the application at the specified index from the list and returns it.

New in version 0.0.5.

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

quit()[source]

Quits (terminates) all applications in the list. Synonymous with terminate().

Example 1:: Quit all visible running applications

>>> import PyXA
>>> apps = PyXA.running_applications()
>>> apps.quit()

New in version 0.0.5.

terminate()[source]

Quits (terminates) all applications in the list. Synonymous with quit().

Example 1:: Terminate all visible running applications

>>> import PyXA
>>> apps = PyXA.running_applications()
>>> apps.terminate()

New in version 0.0.5.

unhide()[source]

Unhides all applications in the list.

Example 1:: Hide then unhide all visible running applications

>>> import PyXA
>>> apps = PyXA.running_applications()
>>> apps.hide()
>>> apps.unhide()

See also

hide()

New in version 0.0.5.

windows() → XAList[source]

Retrieves a list of every window belonging to each application in the list.

Operations on the list of windows will specialized to scriptable and non-scriptable application window operations as necessary.

Returns:: A list containing both scriptable and non-scriptable windows
Return type:: XAList
Example:

>>> import PyXA
>>> windows = PyXA.running_applications().windows()
>>> windows.collapse()
>>> sleep(1)
>>> windows.uncollapse()

Changed in version 0.1.1: Now returns an instance of XAWindowList instead of XACombinedWindowList.

New in version 0.0.5.

class PyXA.XABase.XAApplicationPicker(title: str | None = None, prompt: str | None = None, multiple_selections_allowed: bool = False)[source]

Bases: XAObject

An application selection window.

New in version 0.1.0.

Attributes:

`__annotations__`
`__module__`
`multiple_selections_allowed`	Whether to allow multiple items to be selected
`prompt`	The prompt to be displayed in the dialog box
`title`	The dialog window title

Methods:

`__init__`([title, prompt, ...])	Instantiates a PyXA scripting object.
`display`()	Displays the application chooser, waits for the user to select an application or cancel, then returns the selected application's name or None if cancelled.

__annotations__ = {'multiple_selections_allowed': 'bool', 'prompt': 'str', 'title': 'str'}

__init__(title: str | None = None, prompt: str | None = None, multiple_selections_allowed: bool = False)[source]

Instantiates a PyXA scripting object.

Parameters:: properties (dict, optional) – A dictionary of properties to assign to this object.

Changed in version 0.0.3: Removed on-the-fly creation of class attributes. All objects should concretely define their properties.

New in version 0.0.1.

__module__ = 'PyXA.XABase'

display() → str[source]

Displays the application chooser, waits for the user to select an application or cancel, then returns the selected application’s name or None if cancelled.

Returns:: The name of the selected application
Return type:: str

New in version 0.0.8.

multiple_selections_allowed: bool: Whether to allow multiple items to be selected

prompt: str: The prompt to be displayed in the dialog box

title: str: The dialog window title

class PyXA.XABase.XAAttachment(properties)[source]

Bases: XAObject

A class for managing and interacting with attachments in text documents.

New in version 0.0.1.

Attributes:

`__annotations__`
`__module__`

Methods:

__init__(properties)

Instantiates a PyXA scripting object.

__annotations__ = {}

__init__(properties)[source]

Instantiates a PyXA scripting object.

Parameters:: properties (dict, optional) – A dictionary of properties to assign to this object.

Changed in version 0.0.3: Removed on-the-fly creation of class attributes. All objects should concretely define their properties.

New in version 0.0.1.

__module__ = 'PyXA.XABase'

class PyXA.XABase.XAAttachmentList(properties: dict, filter: dict | None = None)[source]

Bases: XATextList

A wrapper around lists of text attachments that employs fast enumeration techniques.

New in version 0.0.5.

Attributes:

`__annotations__`
`__module__`

Methods:

__init__(properties[, filter])

Creates an efficient wrapper object around a list of scriptable elements.

__annotations__ = {}

__init__(properties: dict, filter: dict | None = None)[source]

Creates an efficient wrapper object around a list of scriptable elements.

Parameters:

properties (dict) – PyXA properties passed to this object for utility purposes
object_class (type, optional) – _description_, defaults to None
filter (Union[dict, None], optional) – A dictionary of properties and values to filter items by, defaults to None

Changed in version 0.0.8: The filter property is deprecated and will be removed in a future version. Use the filter() method instead.

New in version 0.0.3.

__module__ = 'PyXA.XABase'

class PyXA.XABase.XAAttributeRun(properties)[source]

Bases: XAText

A class for managing and interacting with attribute runs in text documents.

New in version 0.0.1.

Attributes:

`__annotations__`
`__module__`

Methods:

__init__(properties)

Instantiates a PyXA scripting object.

__annotations__ = {'color': 'XAColor', 'font': 'str', 'size': 'int', 'text': 'str'}

__init__(properties)[source]

Instantiates a PyXA scripting object.

Parameters:: properties (dict, optional) – A dictionary of properties to assign to this object.

Changed in version 0.0.3: Removed on-the-fly creation of class attributes. All objects should concretely define their properties.

New in version 0.0.1.

__module__ = 'PyXA.XABase'

class PyXA.XABase.XAAttributeRunList(properties: dict, filter: dict | None = None)[source]

Bases: XATextList

A wrapper around lists of attribute runs that employs fast enumeration techniques.

New in version 0.0.5.

Attributes:

`__annotations__`
`__module__`

Methods:

__init__(properties[, filter])

Creates an efficient wrapper object around a list of scriptable elements.

__annotations__ = {}

__init__(properties: dict, filter: dict | None = None)[source]

Creates an efficient wrapper object around a list of scriptable elements.

Parameters:

properties (dict) – PyXA properties passed to this object for utility purposes
object_class (type, optional) – _description_, defaults to None
filter (Union[dict, None], optional) – A dictionary of properties and values to filter items by, defaults to None

Changed in version 0.0.8: The filter property is deprecated and will be removed in a future version. Use the filter() method instead.

New in version 0.0.3.

__module__ = 'PyXA.XABase'

class PyXA.XABase.XACharacter(properties)[source]

Bases: XAText

A class for managing and interacting with characters in text documents.

New in version 0.0.1.

Attributes:

`__annotations__`
`__module__`

Methods:

__init__(properties)

Instantiates a PyXA scripting object.

__annotations__ = {'color': 'XAColor', 'font': 'str', 'size': 'int', 'text': 'str'}

__init__(properties)[source]

Instantiates a PyXA scripting object.

Parameters:: properties (dict, optional) – A dictionary of properties to assign to this object.

Changed in version 0.0.3: Removed on-the-fly creation of class attributes. All objects should concretely define their properties.

New in version 0.0.1.

__module__ = 'PyXA.XABase'

class PyXA.XABase.XACharacterList(properties: dict, filter: dict | None = None)[source]

Bases: XATextList

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

New in version 0.0.5.

Attributes:

`__annotations__`
`__module__`

Methods:

__init__(properties[, filter])

Creates an efficient wrapper object around a list of scriptable elements.

__annotations__ = {}

__init__(properties: dict, filter: dict | None = None)[source]

Creates an efficient wrapper object around a list of scriptable elements.

Parameters:

properties (dict) – PyXA properties passed to this object for utility purposes
object_class (type, optional) – _description_, defaults to None
filter (Union[dict, None], optional) – A dictionary of properties and values to filter items by, defaults to None

Changed in version 0.0.8: The filter property is deprecated and will be removed in a future version. Use the filter() method instead.

New in version 0.0.3.

__module__ = 'PyXA.XABase'

class PyXA.XABase.XAClassicDomainObject(properties)[source]

Bases: XADomain

The Classic domain in the file system.

New in version 0.1.0.

Attributes:

`__annotations__`
`__module__`
`apple_menu_folder`	The Apple Menu Items folder.
`control_panels_folder`	The Control Panels folder.
`control_strip_modules_folder`	The Control Strip Modules folder.
`desktop_folder`	The Classic Desktop folder.
`extensions_folder`	The Extensions folder.
`fonts_folder`	The Fonts folder.
`launcher_items_folder`	The Launcher Items folder.
`preferences_folder`	The Classic Preferences folder.
`shutdown_folder`	The Shutdown Items folder.
`startup_items_folder`	The StartupItems folder.
`system_folder`	The System folder.

Methods:

`__init__`(properties)	Instantiates a PyXA scripting object.
`folders`([filter])	Returns a list of folders, as PyXA objects, matching the given filter.

__annotations__ = {}

__init__(properties)[source]

Instantiates a PyXA scripting object.

Parameters:: properties (dict, optional) – A dictionary of properties to assign to this object.

Changed in version 0.0.3: Removed on-the-fly creation of class attributes. All objects should concretely define their properties.

New in version 0.0.1.

__module__ = 'PyXA.XABase'

property apple_menu_folder: XAFolder: The Apple Menu Items folder.

New in version 0.1.0.

property control_panels_folder: XAFolder: The Control Panels folder.

New in version 0.1.0.

property control_strip_modules_folder: XAFolder: The Control Strip Modules folder.

New in version 0.1.0.

property desktop_folder: XAFolder: The Classic Desktop folder.

New in version 0.1.0.

property extensions_folder: XAFolder: The Extensions folder.

New in version 0.1.0.

folders(filter: dict | None = None) → XAFolderList[source]: Returns a list of folders, as PyXA objects, matching the given filter.

New in version 0.1.0.

property fonts_folder: XAFolder: The Fonts folder.

New in version 0.1.0.

property launcher_items_folder: XAFolder: The Launcher Items folder.

New in version 0.1.0.

property preferences_folder: XAFolder: The Classic Preferences folder.

New in version 0.1.0.

property shutdown_folder: XAFolder: The Shutdown Items folder.

New in version 0.1.0.

property startup_items_folder: XAFolder: The StartupItems folder.

New in version 0.1.0.

property system_folder: XAFolder: The System folder.

New in version 0.1.0.

class PyXA.XABase.XAClipboard[source]

Bases: XAObject

A wrapper class for managing and interacting with the system clipboard.

New in version 0.0.5.

Attributes:

`__annotations__`
`__module__`
`content`	The content of the clipboard.

Methods:

`__init__`()	Instantiates a PyXA scripting object.
`clear`()	Clears the system clipboard.
`get_images`()	Retrieves image type data from the clipboard, as instances of `XAImage`, if any such data exists.
`get_strings`()	Retrieves string type data from the clipboard, if any such data exists.
`get_urls`()	Retrieves URL type data from the clipboard, as instances of `XAURL` and `XAPath`, if any such data exists.
`set_contents`(content)	Sets the content of the clipboard

__annotations__ = {}

__init__()[source]

Instantiates a PyXA scripting object.

Parameters:: properties (dict, optional) – A dictionary of properties to assign to this object.

Changed in version 0.0.3: Removed on-the-fly creation of class attributes. All objects should concretely define their properties.

New in version 0.0.1.

__module__ = 'PyXA.XABase'

clear()[source]: Clears the system clipboard.

New in version 0.0.5.

property content: dict[str, list[Any]]: The content of the clipboard.

get_images() → list[XAImage][source]

Retrieves image type data from the clipboard, as instances of XAImage, if any such data exists.

Returns:: The list of images currently copied to the clipboard
Return type:: list[XAImage]

New in version 0.0.8.

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

Retrieves string type data from the clipboard, if any such data exists.

Returns:: The list of strings currently copied to the clipboard
Return type:: list[str]

New in version 0.0.8.

get_urls() → list[XAURL][source]

Retrieves URL type data from the clipboard, as instances of XAURL and XAPath, if any such data exists.

Returns:: The list of file URLs and web URLs currently copied to the clipboard
Return type:: list[XAURL]

New in version 0.0.8.

set_contents(content: list[Any])[source]

Sets the content of the clipboard

Parameters:: content (list[Any]) – A list of the content to add fill the clipboard with.

Deprecated since version 0.0.8: Set the content property directly instead.

New in version 0.0.5.

class PyXA.XABase.XAColor(*args)[source]

Bases: Color, XAObject, XAClipboardCodable

Attributes:

`__annotations__`
`__module__`

Methods:

`__init__`(*args)	Instantiates a PyXA scripting object.
`get_clipboard_representation`()	Gets a clipboard-codable representation of the color.

__annotations__ = {}

__init__(*args)[source]

Instantiates a PyXA scripting object.

Parameters:: properties (dict, optional) – A dictionary of properties to assign to this object.

Changed in version 0.0.3: Removed on-the-fly creation of class attributes. All objects should concretely define their properties.

New in version 0.0.1.

__module__ = 'PyXA.XABase'

get_clipboard_representation() → NSColor[source]

Gets a clipboard-codable representation of the color.

When the clipboard content is set to a color, the raw color data is added to the clipboard.

Returns:: The raw color data
Return type:: AppKit.NSColor

New in version 0.1.0.

class PyXA.XABase.XAColorList(properties: dict, filter: dict | None = None)[source]

Bases: XATextList

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

New in version 0.0.6.

Attributes:

`__annotations__`
`__module__`

Methods:

__init__(properties[, filter])

Creates an efficient wrapper object around a list of scriptable elements.

__annotations__ = {}

__init__(properties: dict, filter: dict | None = None)[source]

Creates an efficient wrapper object around a list of scriptable elements.

Parameters:

properties (dict) – PyXA properties passed to this object for utility purposes
object_class (type, optional) – _description_, defaults to None
filter (Union[dict, None], optional) – A dictionary of properties and values to filter items by, defaults to None

Changed in version 0.0.8: The filter property is deprecated and will be removed in a future version. Use the filter() method instead.

New in version 0.0.3.

__module__ = 'PyXA.XABase'

class PyXA.XABase.XAColorPicker(style: XAColorPickerStyle = XAColorPickerStyle.COLOR_WHEEL)[source]

Bases: XAObject

A class for creating and interacting with a color picker window.

New in version 0.0.5.

Attributes:

`__annotations__`
`__module__`

Methods:

`__init__`([style])	Instantiates a PyXA scripting object.
`display`()	Displays the color picker.

__annotations__ = {}

__init__(style: XAColorPickerStyle = XAColorPickerStyle.COLOR_WHEEL)[source]

Instantiates a PyXA scripting object.

Parameters:: properties (dict, optional) – A dictionary of properties to assign to this object.

Changed in version 0.0.3: Removed on-the-fly creation of class attributes. All objects should concretely define their properties.

New in version 0.0.1.

__module__ = 'PyXA.XABase'

display() → XAColor[source]

Displays the color picker.

Returns:: The color that the user selected
Return type:: XAColor

New in version 0.0.5.

class PyXA.XABase.XAColorPickerStyle(value)[source]

Bases: Enum

Options for which tab a color picker should display when first opened.

Attributes:

`CMYK_SLIDERS`
`COLOR_LIST`
`COLOR_WHEEL`
`CRAYONS`
`GRAYSCALE`
`HSB_SLIDERS`
`IMAGE_PALETTE`
`RGB_SLIDERS`
`__module__`

CMYK_SLIDERS = 2

COLOR_LIST = 5

COLOR_WHEEL = 6

CRAYONS = 7

GRAYSCALE = 0

HSB_SLIDERS = 3

IMAGE_PALETTE = 4

RGB_SLIDERS = 1

__module__ = 'PyXA.XABase'

Bases: XAObject

A custom dialog window.

New in version 0.0.8.

Attributes:

`__annotations__`
`__module__`

Methods:

`__init__`([text, title, buttons, ...])	Instantiates a PyXA scripting object.
`display`()	Displays the dialog, waits for the user to select an option or cancel, then returns the selected button or None if cancelled.

__annotations__ = {'buttons': 'Union[None, list[Union[str, int]]]', 'cancel_button': 'Union[str, int, None]', 'default_answer': 'Union[str, int, None]', 'default_button': 'Union[str, int, None]', 'hidden_answer': 'bool', 'icon': 'Union[str, None]', 'text': 'str', 'title': 'str'}

Instantiates a PyXA scripting object.

Parameters:: properties (dict, optional) – A dictionary of properties to assign to this object.

Changed in version 0.0.3: Removed on-the-fly creation of class attributes. All objects should concretely define their properties.

New in version 0.0.1.

__module__ = 'PyXA.XABase'

buttons: None | list[str | int]

cancel_button: str | int | None

default_answer: str | int | None

default_button: str | int | None

display() → str | int | None | list[str][source]

Displays the dialog, waits for the user to select an option or cancel, then returns the selected button or None if cancelled.

Returns:: The selected button or None if no value was selected
Return type:: Union[str, int, None, list[str]]

New in version 0.0.8.

hidden_answer: bool

icon: str | None

text: str

title: str

class PyXA.XABase.XADisk(properties)[source]

Bases: XADiskItem

A disk in the file system.

New in version 0.1.0.

Attributes:

`__annotations__`
`__module__`
`capacity`	The total number of bytes (free or used) on the disk.
`ejectable`	Whether the media can be ejected (floppies, CD's, and so on).
`format`	The file system format of the disk.
`free_space`	The number of free bytes left on the disk.
`ignore_privileges`	Whether to ignore permissions on this disk.
`local_volume`	Whether the media is a local volume (as opposed to a file server).
`server`	The server on which the disk resides, AFP volumes only.
`startup`	Whether this disk is the boot disk.
`zone`	The zone in which the disk's server resides, AFP volumes only.

Methods:

`__init__`(properties)	Instantiates a PyXA scripting object.
`aliases`([filter])	Returns a list of aliases, as PyXA objects, matching the given filter.
`disk_items`([filter])	Returns a list of disk items, as PyXA objects, matching the given filter.
`file_packages`([filter])	Returns a list of file packages, as PyXA objects, matching the given filter.
`files`([filter])	Returns a list of files, as PyXA objects, matching the given filter.
`folders`([filter])	Returns a list of folders, as PyXA objects, matching the given filter.

__annotations__ = {}

__init__(properties)[source]

Instantiates a PyXA scripting object.

Parameters:: properties (dict, optional) – A dictionary of properties to assign to this object.

Changed in version 0.0.3: Removed on-the-fly creation of class attributes. All objects should concretely define their properties.

New in version 0.0.1.

__module__ = 'PyXA.XABase'

aliases(filter: dict | None = None) → XAAliasList[source]: Returns a list of aliases, as PyXA objects, matching the given filter.

New in version 0.1.0.

property capacity: float: The total number of bytes (free or used) on the disk.

New in version 0.1.0.

disk_items(filter: dict | None = None) → XADiskItemList[source]: Returns a list of disk items, as PyXA objects, matching the given filter.

New in version 0.1.0.

property ejectable: bool: Whether the media can be ejected (floppies, CD’s, and so on).

New in version 0.1.0.

file_packages(filter: dict | None = None) → XAFilePackageList[source]: Returns a list of file packages, as PyXA objects, matching the given filter.

New in version 0.1.0.

files(filter: dict | None = None) → XAFileList[source]: Returns a list of files, as PyXA objects, matching the given filter.

New in version 0.1.0.

folders(filter: dict | None = None) → XAFolderList[source]: Returns a list of folders, as PyXA objects, matching the given filter.

New in version 0.1.0.

property format: Format: The file system format of the disk.

New in version 0.1.0.

property free_space: float: The number of free bytes left on the disk.

New in version 0.1.0.

property ignore_privileges: bool: Whether to ignore permissions on this disk.

New in version 0.1.0.

property local_volume: bool: Whether the media is a local volume (as opposed to a file server).

New in version 0.1.0.

property server: str: The server on which the disk resides, AFP volumes only.

New in version 0.1.0.

property startup: bool: Whether this disk is the boot disk.

New in version 0.1.0.

property zone: str: The zone in which the disk’s server resides, AFP volumes only.

New in version 0.1.0.

class PyXA.XABase.XADiskItem(properties)[source]

Bases: XAObject, XAPathLike

An item stored in the file system.

New in version 0.1.0.

Attributes:

`__annotations__`
`__module__`
`busy_status`	Whether the disk item is busy.
`container`	The folder or disk which has this disk item as an element.
`creation_date`	The date on which the disk item was created.
`displayed_name`	The name of the disk item as displayed in the User Interface.
`id`	The unique ID of the disk item.
`modification_date`	The date on which the disk item was last modified.
`name`	The name of the disk item.
`name_extension`	The extension portion of the name.
`package_folder`	Whether the disk item is a package.
`path`	The file system path of the disk item.
`physical_size`	The actual space used by the disk item on disk.
`posix_path`	The POSIX file system path of the disk item.
`size`	The logical size of the disk item.
`url`	The URL of the disk item.
`visible`	Whether the disk item is visible.
`volume`	The volume on which the disk item resides.

Methods:

`__init__`(properties)	Instantiates a PyXA scripting object.
`__repr__`()	Return repr(self).
`get_path_representation`()	Gets a representation of the object that can be used to initialize an `XAPath` object.
`move_to`(folder)	Moves the disk item to the specified location.
`open`()	Opens the item in its default application.

__annotations__ = {}

__init__(properties)[source]

Instantiates a PyXA scripting object.

Parameters:: properties (dict, optional) – A dictionary of properties to assign to this object.

Changed in version 0.0.3: Removed on-the-fly creation of class attributes. All objects should concretely define their properties.

New in version 0.0.1.

__module__ = 'PyXA.XABase'

__repr__()[source]: Return repr(self).

property busy_status: bool: Whether the disk item is busy.

New in version 0.1.0.

property container: XADiskItem: The folder or disk which has this disk item as an element.

New in version 0.1.0.

property creation_date: datetime: The date on which the disk item was created.

New in version 0.1.0.

property displayed_name: str: The name of the disk item as displayed in the User Interface.

New in version 0.1.0.

get_path_representation() → XAPath[source]

Gets a representation of the object that can be used to initialize an XAPath object.

This method must be overriden in child classes of XAPathLike.

Returns:: The XAPath-compatible form of the object, or None if no such form exists
Return type:: Any

property id: str: The unique ID of the disk item.

New in version 0.1.0.

property modification_date: datetime: The date on which the disk item was last modified.

New in version 0.1.0.

move_to(folder: str | XAPath | XAFolder) → XADiskItem[source]

Moves the disk item to the specified location.

Parameters:: folder (Union[str, XAPath, XAFolder]) – The folder location to move the item to
Returns:: The disk item object
Return type:: XADiskItem

New in version 0.2.1.

property name: str: The name of the disk item.

New in version 0.1.0.

property name_extension: str: The extension portion of the name.

New in version 0.1.0.

open() → XADiskItem[source]

Opens the item in its default application.

Returns:: The item object
Return type:: XADiskItem

New in version 0.1.1.

property package_folder: bool: Whether the disk item is a package.

New in version 0.1.0.

property path: XAPath: The file system path of the disk item.

New in version 0.1.0.

property physical_size: int: The actual space used by the disk item on disk.

New in version 0.1.0.

property posix_path: XAPath: The POSIX file system path of the disk item.

New in version 0.1.0.

property size: int: The logical size of the disk item.

New in version 0.1.0.

property url: XAURL: The URL of the disk item.

New in version 0.1.0.

property visible: bool: Whether the disk item is visible.

New in version 0.1.0.

property volume: str: The volume on which the disk item resides.

New in version 0.1.0.

class PyXA.XABase.XADiskItemList(properties: dict, filter: dict | None = None, object_class=None)[source]

Bases: XAList

A wrapper around lists of disk items that employs fast enumeration techniques.

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

New in version 0.1.0.

Attributes:

`__annotations__`
`__module__`

Methods:

`__init__`(properties[, filter, object_class])	Creates an efficient wrapper object around a list of scriptable elements.
`__repr__`()	Return repr(self).
`busy_status`()
`by_busy_status`(busy_status)
`by_container`(container)
`by_creation_date`(creation_date)
`by_displayed_name`(displayed_name)
`by_id`(id)
`by_modification_date`(modification_date)
`by_name`(name)
`by_name_extension`(name_extension)
`by_package_folder`(package_folder)
`by_path`(path)
`by_physical_size`(physical_size)
`by_posix_path`(posix_path)
`by_size`(size)
`by_url`(url)
`by_visible`(visible)
`by_volume`(volume)
`container`()
`creation_date`()
`displayed_name`()
`id`()
`modification_date`()
`move_to`(folder)	Moves all disk items in the list to the specified location.
`name`()
`name_extension`()
`package_folder`()
`path`()
`physical_size`()
`posix_path`()
`size`()
`url`()
`visible`()
`volume`()

__annotations__ = {}

__init__(properties: dict, filter: dict | None = None, object_class=None)[source]

Creates an efficient wrapper object around a list of scriptable elements.

Parameters:

properties (dict) – PyXA properties passed to this object for utility purposes
object_class (type, optional) – _description_, defaults to None
filter (Union[dict, None], optional) – A dictionary of properties and values to filter items by, defaults to None

Changed in version 0.0.8: The filter property is deprecated and will be removed in a future version. Use the filter() method instead.

New in version 0.0.3.

__module__ = 'PyXA.XABase'

__repr__()[source]: Return repr(self).

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

by_busy_status(busy_status: bool) → XADiskItem | None[source]

by_container(container: XADiskItem) → XADiskItem | None[source]

by_creation_date(creation_date: datetime) → XADiskItem | None[source]

by_displayed_name(displayed_name: str) → XADiskItem | None[source]

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

by_modification_date(modification_date: datetime) → XADiskItem | None[source]

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

by_name_extension(name_extension: str) → XADiskItem | None[source]

by_package_folder(package_folder: bool) → XADiskItem | None[source]

by_path(path: XAPath | str) → XADiskItem | None[source]

by_physical_size(physical_size: int) → XADiskItem | None[source]

by_posix_path(posix_path: XAPath | str) → XADiskItem | None[source]

by_size(size: int) → XADiskItem | None[source]

by_url(url: XAURL) → XADiskItem | None[source]

by_visible(visible: bool) → XADiskItem | None[source]

by_volume(volume: str) → XADiskItem | None[source]

container() → XADiskItemList[source]

creation_date() → list[datetime][source]

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

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

modification_date() → list[datetime][source]

move_to(folder: str | XAPath | XAFolder) → XADiskItem[source]

Moves all disk items in the list to the specified location.

Parameters:: folder (Union[str, XAPath, XAFolder]) – The folder location to move the items to
Returns:: The list of disk items
Return type:: XADiskItem

New in version 0.2.1.

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

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

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

path() → list[XAPath][source]

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

posix_path() → list[XAPath][source]

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

url() → list[XAURL][source]

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

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

class PyXA.XABase.XADiskList(properties: dict, filter: dict | None = None)[source]

Bases: XADiskItemList

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

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

New in version 0.1.0.

Attributes:

`__annotations__`
`__module__`

Methods:

`__init__`(properties[, filter])	Creates an efficient wrapper object around a list of scriptable elements.
`by_capacity`(capacity)
`by_ejectable`(ejectable)
`by_format`(format)
`by_free_space`(free_space)
`by_ignore_privileges`(ignore_privileges)
`by_local_volume`(local_volume)
`by_server`(server)
`by_startup`(startup)
`by_zone`(zone)
`capacity`()
`ejectable`()
`format`()
`free_space`()
`ignore_privileges`()
`local_volume`()
`server`()
`startup`()
`zone`()

__annotations__ = {}

__init__(properties: dict, filter: dict | None = None)[source]

Creates an efficient wrapper object around a list of scriptable elements.

Parameters:

properties (dict) – PyXA properties passed to this object for utility purposes
object_class (type, optional) – _description_, defaults to None
filter (Union[dict, None], optional) – A dictionary of properties and values to filter items by, defaults to None

Changed in version 0.0.8: The filter property is deprecated and will be removed in a future version. Use the filter() method instead.

New in version 0.0.3.

__module__ = 'PyXA.XABase'

by_capacity(capacity: float) → XADisk | None[source]

by_ejectable(ejectable: bool) → XADisk | None[source]

by_format(format: Format) → XADisk | None[source]

by_free_space(free_space: float) → XADisk | None[source]

by_ignore_privileges(ignore_privileges: bool) → XADisk | None[source]

by_local_volume(local_volume: bool) → XADisk | None[source]

by_server(server: str) → XADisk | None[source]

by_startup(startup: bool) → XADisk | None[source]

by_zone(zone: str) → XADisk | None[source]

capacity() → list[float][source]

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

format() → list[XAEventsApplication.Format][source]

free_space() → list[float][source]

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

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

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

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

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

class PyXA.XABase.XADomain(properties)[source]

Bases: XAObject

A domain in the file system.

New in version 0.1.0.

Attributes:

`__annotations__`
`__module__`
`application_support_folder`	The Application Support folder.
`applications_folder`	The Applications folder.
`desktop_pictures_folder`	The Desktop Pictures folder.
`folder_action_scripts_folder`	The Folder Action Scripts folder.
`fonts_folder`	The Fonts folder.
`id`	The unique identifier of the domain.
`library_folder`	The Library folder.
`name`	The name of the domain.
`preferences_folder`	The Preferences folder.
`scripting_additions_folder`	The Scripting Additions folder.
`scripts_folder`	The Scripts folder.
`shared_documents_folder`	The Shared Documents folder.
`speakable_items_folder`	The Speakable Items folder.
`utilities_folder`	The Utilities folder.
`workflows_folder`	The Automator Workflows folder.

Methods:

`__init__`(properties)	Instantiates a PyXA scripting object.
`__repr__`()	Return repr(self).
`folders`([filter])	Returns a list of folders, as PyXA objects, matching the given filter.

__annotations__ = {}

__init__(properties)[source]

Instantiates a PyXA scripting object.

Parameters:: properties (dict, optional) – A dictionary of properties to assign to this object.

Changed in version 0.0.3: Removed on-the-fly creation of class attributes. All objects should concretely define their properties.

New in version 0.0.1.

__module__ = 'PyXA.XABase'

__repr__()[source]: Return repr(self).

property application_support_folder: XAFolder: The Application Support folder.

New in version 0.1.0.

property applications_folder: XAFolder: The Applications folder.

New in version 0.1.0.

property desktop_pictures_folder: XAFolder: The Desktop Pictures folder.

New in version 0.1.0.

property folder_action_scripts_folder: XAFolder: The Folder Action Scripts folder.

New in version 0.1.0.

folders(filter: dict | None = None) → XAFolderList[source]: Returns a list of folders, as PyXA objects, matching the given filter.

New in version 0.1.0.

property fonts_folder: XAFolder: The Fonts folder.

New in version 0.1.0.

property id: str: The unique identifier of the domain.

New in version 0.1.0.

property library_folder: XAFolder: The Library folder.

New in version 0.1.0.

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

New in version 0.1.0.

property preferences_folder: XAFolder: The Preferences folder.

New in version 0.1.0.

property scripting_additions_folder: XAFolder: The Scripting Additions folder.

New in version 0.1.0.

property scripts_folder: XAFolder: The Scripts folder.

New in version 0.1.0.

property shared_documents_folder: XAFolder: The Shared Documents folder.

New in version 0.1.0.

property speakable_items_folder: XAFolder: The Speakable Items folder.

New in version 0.1.0.

property utilities_folder: XAFolder: The Utilities folder.

New in version 0.1.0.

property workflows_folder: XAFolder: The Automator Workflows folder.

New in version 0.1.0.

class PyXA.XABase.XADomainList(properties: dict, filter: dict | None = None)[source]

Bases: XAList

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

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

New in version 0.1.0.

Attributes:

`__annotations__`
`__module__`

Methods:

`__init__`(properties[, filter])	Creates an efficient wrapper object around a list of scriptable elements.
`__repr__`()	Return repr(self).
`by_id`(id)
`by_name`(name)
`id`()
`name`()

__annotations__ = {}

__init__(properties: dict, filter: dict | None = None)[source]

Creates an efficient wrapper object around a list of scriptable elements.

Parameters:

properties (dict) – PyXA properties passed to this object for utility purposes
object_class (type, optional) – _description_, defaults to None
filter (Union[dict, None], optional) – A dictionary of properties and values to filter items by, defaults to None

Changed in version 0.0.8: The filter property is deprecated and will be removed in a future version. Use the filter() method instead.

New in version 0.0.3.

__module__ = 'PyXA.XABase'

__repr__()[source]: Return repr(self).

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

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

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

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

class PyXA.XABase.XAEventsApplication[source]

Bases: XACanOpenPath

A base class for the System and Image events applications.

New in version 0.1.0.

Classes:

Format(value)

Disk format options.

Attributes:

`__annotations__`
`__module__`

class Format(value)[source]

Bases: Enum

Disk format options.

Attributes:

`APPLESHARE`
`APPLE_PHOTO`
`AUDIO`
`HIGH_SIERRA`
`ISO_9660`
`MACOS`
`MACOS_EXTENDED`
`MSDOS`
`NFS`
`PRODOS`
`QUICKTAKE`
`UDF`
`UFS`
`UNKNOWN`
`WEBDAV`
`__module__`

APPLESHARE = 1684431219

APPLE_PHOTO = 1684435048

AUDIO = 1684431221

HIGH_SIERRA = 1684433011

ISO_9660 = 1717844278

MACOS = 1684432998

MACOS_EXTENDED = 1684432939

MSDOS = 1684434291

NFS = 1684434534

PRODOS = 1684435058

QUICKTAKE = 1684435316

UDF = 1684436324

UFS = 1684436326

UNKNOWN = 1684415524

WEBDAV = 1684436836

__module__ = 'PyXA.XABase'

__annotations__ = {}

__module__ = 'PyXA.XABase'

class PyXA.XABase.XAFile(properties)[source]

Bases: XADiskItem

A file in the file system.

New in version 0.1.0.

Attributes:

`__annotations__`
`__module__`
`creator_type`	The OSType identifying the application that created the file.
`default_application`	The application that will launch if the file is opened.
`file_type`	The OSType identifying the type of data contained in the file.
`kind`	The kind of file, as shown in Finder.
`product_version`	The version of the product (visible at the top of the "Get Info" window).
`short_version`	The short version of the file.
`stationery`	Whether the file is a stationery pad.
`type_identifier`	The type identifier of the file.
`version`	The version of the file (visible at the bottom of the "Get Info" window).

Methods:

__init__(properties)

Instantiates a PyXA scripting object.

__annotations__ = {}

__init__(properties)[source]

Instantiates a PyXA scripting object.

Parameters:: properties (dict, optional) – A dictionary of properties to assign to this object.

Changed in version 0.0.3: Removed on-the-fly creation of class attributes. All objects should concretely define their properties.

New in version 0.0.1.

__module__ = 'PyXA.XABase'

property creator_type: str: The OSType identifying the application that created the file.

New in version 0.1.0.

property default_application: XADiskItem: The application that will launch if the file is opened.

New in version 0.1.0.

property file_type: str: The OSType identifying the type of data contained in the file.

New in version 0.1.0.

property kind: str: The kind of file, as shown in Finder.

New in version 0.1.0.

property product_version: str: The version of the product (visible at the top of the “Get Info” window).

New in version 0.1.0.

property short_version: str: The short version of the file.

New in version 0.1.0.

property stationery: bool: Whether the file is a stationery pad.

New in version 0.1.0.

property type_identifier: str: The type identifier of the file.

New in version 0.1.0.

property version: str: The version of the file (visible at the bottom of the “Get Info” window).

New in version 0.1.0.

class PyXA.XABase.XAFileList(properties: dict, filter: dict | None = None, object_class=None)[source]

Bases: XADiskItemList

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

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

New in version 0.1.0.

Attributes:

`__annotations__`
`__module__`

Methods:

`__init__`(properties[, filter, object_class])	Creates an efficient wrapper object around a list of scriptable elements.
`by_creator_type`(creator_type)
`by_default_application`(default_application)
`by_file_type`(file_type)
`by_kind`(kind)
`by_product_version`(product_version)
`by_short_version`(short_version)
`by_stationery`(stationery)
`by_type_identifier`(type_identifier)
`by_version`(version)
`creator_type`()
`default_application`()
`file_type`()
`kind`()
`product_version`()
`short_version`()
`stationery`()
`type_identifier`()
`version`()

__annotations__ = {}

__init__(properties: dict, filter: dict | None = None, object_class=None)[source]

Creates an efficient wrapper object around a list of scriptable elements.

Parameters:

properties (dict) – PyXA properties passed to this object for utility purposes
object_class (type, optional) – _description_, defaults to None
filter (Union[dict, None], optional) – A dictionary of properties and values to filter items by, defaults to None

Changed in version 0.0.8: The filter property is deprecated and will be removed in a future version. Use the filter() method instead.

New in version 0.0.3.

__module__ = 'PyXA.XABase'

by_creator_type(creator_type: str) → XAFile | None[source]

by_default_application(default_application: XADiskItem) → XAFile | None[source]

by_file_type(file_type: str) → XAFile | None[source]

by_kind(kind: str) → XAFile | None[source]

by_product_version(product_version: str) → XAFile | None[source]

by_short_version(short_version: str) → XAFile | None[source]

by_stationery(stationery: bool) → XAFile | None[source]

by_type_identifier(type_identifier: str) → XAFile | None[source]

by_version(version: str) → XAFile | None[source]

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

default_application() → XADiskItemList[source]

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

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

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

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

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

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

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

class PyXA.XABase.XAFileNameDialog(prompt: str = 'Specify file name and location', default_name: str = 'New File', default_location: str | None = None)[source]

Bases: XAObject

A file name input window.

New in version 0.0.8.

Attributes:

`__annotations__`
`__module__`
`default_location`	The default file location
`default_name`	The default name for the new file
`prompt`	The prompt to display in the dialog box

Methods:

`__init__`([prompt, default_name, ...])	Instantiates a PyXA scripting object.
`display`()	Displays the file name input window, waits for the user to input a name and location or cancel, then returns the specified file URL or None if cancelled.

__annotations__ = {'default_location': 'Union[str, None]', 'default_name': 'str', 'prompt': 'str'}

__init__(prompt: str = 'Specify file name and location', default_name: str = 'New File', default_location: str | None = None)[source]

Instantiates a PyXA scripting object.

Parameters:: properties (dict, optional) – A dictionary of properties to assign to this object.

Changed in version 0.0.3: Removed on-the-fly creation of class attributes. All objects should concretely define their properties.

New in version 0.0.1.

__module__ = 'PyXA.XABase'

default_location: str | None: The default file location

default_name: str: The default name for the new file

display() → XAPath | None[source]

Displays the file name input window, waits for the user to input a name and location or cancel, then returns the specified file URL or None if cancelled.

Returns:: The specified file URL or None if no file name was inputted
Return type:: Union[XAPath, None]

New in version 0.0.8.

prompt: str: The prompt to display in the dialog box

class PyXA.XABase.XAFilePackage(properties)[source]

Bases: XAFile

A file package in the file system.

New in version 0.1.0.

Attributes:

`__annotations__`
`__module__`

Methods:

`__init__`(properties)	Instantiates a PyXA scripting object.
`aliases`([filter])	Returns a list of aliases, as PyXA objects, matching the given filter.
`disk_items`([filter])	Returns a list of disk items, as PyXA objects, matching the given filter.
`file_packages`([filter])	Returns a list of file packages, as PyXA objects, matching the given filter.
`files`([filter])	Returns a list of files, as PyXA objects, matching the given filter.
`folders`([filter])	Returns a list of folders, as PyXA objects, matching the given filter.

__annotations__ = {}

__init__(properties)[source]

Instantiates a PyXA scripting object.

Parameters:: properties (dict, optional) – A dictionary of properties to assign to this object.

Changed in version 0.0.3: Removed on-the-fly creation of class attributes. All objects should concretely define their properties.

New in version 0.0.1.

__module__ = 'PyXA.XABase'

aliases(filter: dict | None = None) → XAAliasList[source]: Returns a list of aliases, as PyXA objects, matching the given filter.

New in version 0.1.0.

disk_items(filter: dict | None = None) → XADiskItemList[source]: Returns a list of disk items, as PyXA objects, matching the given filter.

New in version 0.1.0.

file_packages(filter: dict | None = None) → XAFilePackageList[source]: Returns a list of file packages, as PyXA objects, matching the given filter.

New in version 0.1.0.

files(filter: dict | None = None) → XAFileList[source]: Returns a list of files, as PyXA objects, matching the given filter.

New in version 0.1.0.

folders(filter: dict | None = None) → XAFolderList[source]: Returns a list of folders, as PyXA objects, matching the given filter.

New in version 0.1.0.

class PyXA.XABase.XAFilePackageList(properties: dict, filter: dict | None = None)[source]

Bases: XAFileList

A wrapper around lists of file packages that employs fast enumeration techniques.

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

New in version 0.1.0.

Attributes:

`__annotations__`
`__module__`

Methods:

__init__(properties[, filter])

Creates an efficient wrapper object around a list of scriptable elements.

__annotations__ = {}

__init__(properties: dict, filter: dict | None = None)[source]

Creates an efficient wrapper object around a list of scriptable elements.

Parameters:

properties (dict) – PyXA properties passed to this object for utility purposes
object_class (type, optional) – _description_, defaults to None
filter (Union[dict, None], optional) – A dictionary of properties and values to filter items by, defaults to None

Changed in version 0.0.8: The filter property is deprecated and will be removed in a future version. Use the filter() method instead.

New in version 0.0.3.

__module__ = 'PyXA.XABase'

class PyXA.XABase.XAFilePicker(prompt: str = 'Choose File', types: list[str] | None = None, default_location: str | None = None, show_invisibles: bool = False, multiple_selections_allowed: bool = False, show_package_contents: bool = False)[source]

Bases: XAObject

A file selection window.

New in version 0.0.8.

Attributes:

`__annotations__`
`__module__`
`default_location`	The default file location
`prompt`	The prompt to display in the dialog box
`types`	The file types/type identifiers to allow for selection

Methods:

`__init__`([prompt, types, default_location, ...])	Instantiates a PyXA scripting object.
`display`()	Displays the file chooser, waits for the user to select a file or cancel, then returns the selected file URL or None if cancelled.

__annotations__ = {'default_location': 'Union[str, None]', 'multiple_selections_allowed': 'bool', 'prompt': 'str', 'show_invisibles': 'bool', 'show_package_contents': 'bool', 'types': 'list[str]'}

__init__(prompt: str = 'Choose File', types: list[str] | None = None, default_location: str | None = None, show_invisibles: bool = False, multiple_selections_allowed: bool = False, show_package_contents: bool = False)[source]

Instantiates a PyXA scripting object.

Parameters:: properties (dict, optional) – A dictionary of properties to assign to this object.

Changed in version 0.0.3: Removed on-the-fly creation of class attributes. All objects should concretely define their properties.

New in version 0.0.1.

__module__ = 'PyXA.XABase'

default_location: str | None: The default file location

display() → XAPath | None[source]

Displays the file chooser, waits for the user to select a file or cancel, then returns the selected file URL or None if cancelled.

Returns:: The selected file URL or None if no file was selected
Return type:: Union[XAPath, None]

New in version 0.0.8.

multiple_selections_allowed: bool

prompt: str: The prompt to display in the dialog box

show_invisibles: bool

show_package_contents: bool

types: list[str]: The file types/type identifiers to allow for selection

class PyXA.XABase.XAFolder(properties)[source]

Bases: XADiskItem

A folder in the file system.

New in version 0.1.0.

Attributes:

`__annotations__`
`__module__`

Methods:

`__init__`(properties)	Instantiates a PyXA scripting object.
`aliases`([filter])	Returns a list of aliases, as PyXA objects, matching the given filter.
`disk_items`([filter])	Returns a list of disk items, as PyXA objects, matching the given filter.
`file_packages`([filter])	Returns a list of file packages, as PyXA objects, matching the given filter.
`files`([filter])	Returns a list of files, as PyXA objects, matching the given filter.
`folders`([filter])	Returns a list of folders, as PyXA objects, matching the given filter.

__annotations__ = {}

__init__(properties)[source]

Instantiates a PyXA scripting object.

Parameters:: properties (dict, optional) – A dictionary of properties to assign to this object.

Changed in version 0.0.3: Removed on-the-fly creation of class attributes. All objects should concretely define their properties.

New in version 0.0.1.

__module__ = 'PyXA.XABase'

aliases(filter: dict | None = None) → XAAliasList[source]: Returns a list of aliases, as PyXA objects, matching the given filter.

New in version 0.1.0.

disk_items(filter: dict | None = None) → XADiskItemList[source]: Returns a list of disk items, as PyXA objects, matching the given filter.

New in version 0.1.0.

file_packages(filter: dict | None = None) → XAFilePackageList[source]: Returns a list of file packages, as PyXA objects, matching the given filter.

New in version 0.1.0.

files(filter: dict | None = None) → XAFileList[source]: Returns a list of files, as PyXA objects, matching the given filter.

New in version 0.1.0.

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

Returns a list of folders, as PyXA objects, matching the given filter.

Parameters:: filter (Union[dict, None]) – A dictionary specifying property-value pairs that all returned folders will have, or None
Returns:: The list of folders
Return type:: XAFolderList

New in version 0.1.0.

class PyXA.XABase.XAFolderList(properties: dict, filter: dict | None = None)[source]

Bases: XADiskItemList

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

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

New in version 0.1.0.

Attributes:

`__annotations__`
`__module__`

Methods:

__init__(properties[, filter])

Creates an efficient wrapper object around a list of scriptable elements.

__annotations__ = {}

__init__(properties: dict, filter: dict | None = None)[source]

Creates an efficient wrapper object around a list of scriptable elements.

Parameters:

properties (dict) – PyXA properties passed to this object for utility purposes
object_class (type, optional) – _description_, defaults to None
filter (Union[dict, None], optional) – A dictionary of properties and values to filter items by, defaults to None

Changed in version 0.0.8: The filter property is deprecated and will be removed in a future version. Use the filter() method instead.

New in version 0.0.3.

__module__ = 'PyXA.XABase'

class PyXA.XABase.XAFolderPicker(prompt: str = 'Choose Folder', default_location: str | None = None, show_invisibles: bool = False, multiple_selections_allowed: bool = False, show_package_contents: bool = False)[source]

Bases: XAObject

A folder selection window.

New in version 0.0.8.

Attributes:

`__annotations__`
`__module__`
`default_location`	The default folder location
`prompt`	The prompt to display in the dialog box

Methods:

`__init__`([prompt, default_location, ...])	Instantiates a PyXA scripting object.
`display`()	Displays the folder chooser, waits for the user to select a folder or cancel, then returns the selected folder URL or None if cancelled.

__annotations__ = {'default_location': 'Union[str, None]', 'multiple_selections_allowed': 'bool', 'prompt': 'str', 'show_invisibles': 'bool', 'show_package_contents': 'bool'}

__init__(prompt: str = 'Choose Folder', default_location: str | None = None, show_invisibles: bool = False, multiple_selections_allowed: bool = False, show_package_contents: bool = False)[source]

Instantiates a PyXA scripting object.

Parameters:: properties (dict, optional) – A dictionary of properties to assign to this object.

Changed in version 0.0.3: Removed on-the-fly creation of class attributes. All objects should concretely define their properties.

New in version 0.0.1.

__module__ = 'PyXA.XABase'

default_location: str | None: The default folder location

display() → XAPath | None[source]

Displays the folder chooser, waits for the user to select a folder or cancel, then returns the selected folder URL or None if cancelled.

Returns:: The selected folder URL or None if no folder was selected
Return type:: Union[XAPath, None]

New in version 0.0.8.

multiple_selections_allowed: bool

prompt: str: The prompt to display in the dialog box

show_invisibles: bool

show_package_contents: bool

class PyXA.XABase.XAImage(image_reference: str | XAPath | NSURL | NSImage | None = None)[source]

Bases: Image, XAObject, XAClipboardCodable

A wrapper around NSImage with specialized automation methods.

New in version 0.0.2.

Attributes:

`__annotations__`
`__hash__`
`__module__`
`xa_elem`

Methods:

`__eq__`(other)	Return self==value.
`__init__`([image_reference])	Instantiates a PyXA scripting object.
`auto_enhance`([correct_red_eye, ...])	Attempts to enhance the image by applying suggested filters.
`bloom`([intensity])	Applies a bloom effect to the image.
`bump`([center, radius, curvature])	Creates a concave (inward) or convex (outward) bump at the specified location within the image.
`comic`()	Applies a comic filter to the image.
`crop`(size[, corner])	Crops the image to the specified dimensions.
`crystallize`([crystal_size])	Applies a crystallization filter to the image.
`depth_of_field`([focal_region, intensity, ...])	Applies a depth of field filter to the image, simulating a tilt & shift effect.
`edges`([intensity])	Detects the edges in the image and highlights them colorfully, blackening other areas of the image.
`flip_horizontally`()	Flips the image horizontally.
`flip_vertically`()	Flips the image vertically.
`gaussian_blur`([intensity])	Blurs the image using a Gaussian filter.
`get_clipboard_representation`()	Gets a clipboard-codable representation of the iimage.
`horizontal_stitch`()	Horizontally stacks two or more images.
`invert`()	Inverts the color of the image.
`monochrome`(color[, intensity])	Remaps the colors of the image to shades of the specified color.
`open`()	Initializes one or more images from files.
`outline`([threshold])	Outlines detected edges within the image in black, leaving the rest transparent.
`pinch`([center, intensity])	Creates an inward pinch distortion at the specified location within the image.
`pixellate`([pixel_size])	Pixellates the image.
`pointillize`([point_size])	Applies a pointillization filter to the image.
`reduce_noise`([noise_level, sharpness])	Reduces noise in the image by sharpening areas with a luminance delta below the specified noise level threshold.
`resize`(width[, height])	Resizes the image to the specified width and height.
`rotate`(degrees)	Rotates the image clockwise by the specified number of degrees.
`save`([file_path])	Saves the image to a file on the disk.
`scale`(scale_factor_x[, scale_factor_y])	Scales the image by the specified horizontal and vertical factors.
`sepia`([intensity])	Applies a sepia filter to the image; maps all colors of the image to shades of brown.
`twirl`([center, radius, angle])	Creates a twirl distortion by rotating pixels around the specified location within the image.
`vertical_stitch`()	Vertically stacks two or more images.
`vignette`([intensity])	Applies vignette shading to the corners of the image.

__annotations__ = {'file': 'str', 'modified': 'bool'}

__eq__(other)[source]: Return self==value.

__hash__ = None

__init__(image_reference: str | XAPath | NSURL | NSImage | None = None)[source]

Instantiates a PyXA scripting object.

Parameters:: properties (dict, optional) – A dictionary of properties to assign to this object.

Changed in version 0.0.3: Removed on-the-fly creation of class attributes. All objects should concretely define their properties.

New in version 0.0.1.

__module__ = 'PyXA.XABase'

auto_enhance(correct_red_eye: bool = False, crop_to_features: bool = False, correct_rotation: bool = False) → XAImage[source]

Attempts to enhance the image by applying suggested filters.

Parameters:

correct_red_eye (bool, optional) – Whether to attempt red eye removal, defaults to False
crop_to_features (bool, optional) – Whether to crop the image to focus on the main features with it, defaults to False
correct_rotation (bool, optional) – Whether attempt perspective correction by rotating the image, defaults to False

Returns:

The resulting image after applying the enchantments

Return type:

XAImage

New in version 0.1.0.

bloom(intensity: float = 0.5) → XAImage[source]

Applies a bloom effect to the image. Softens edges and adds a glow.

Parameters:: intensity (float) – The strength of the softening and glow effects, defaults to 0.5
Returns:: The resulting image after applying the filter
Return type:: XAImage

New in version 0.1.0.

bump(center: tuple[int, int] | None = None, radius: float = 300.0, curvature: float = 0.5) → XAImage[source]

Creates a concave (inward) or convex (outward) bump at the specified location within the image.

Parameters:

center (Union[tuple[int, int], None]) – The center point of the effect, or None to use the center of the image, defaults to None
radius (float) – The radius of the bump in pixels, defaults to 300.0
curvature (float) – Controls the direction and intensity of the bump’s curvature. Positive values create convex bumps while negative values create concave bumps. Defaults to 0.5

Returns:

The resulting image after applying the distortion

Return type:

XAImage

New in version 0.1.0.

comic() → XAImage[source]

Applies a comic filter to the image. Outlines edges and applies a color halftone effect.

Returns:: The resulting image after applying the filter
Return type:: XAImage

New in version 0.1.0.

crop(size: tuple[int, int], corner: tuple[int, int] = (0, 0)) → XAImage[source]

Crops the image to the specified dimensions.

Parameters:

size (tuple[int, int]) – The width and height of the resulting image
corner (tuple[int, int], optional) – The bottom-left corner location from which to crop the image, defaults to (0, 0)

Returns:

The image object, modifications included

Return type:

XAImage

New in version 0.1.0.

crystallize(crystal_size: float = 20.0) → XAImage[source]

Applies a crystallization filter to the image. Creates polygon-shaped color blocks by aggregating pixel values.

Parameters:: crystal_size (float) – The radius of the crystals, defaults to 20.0
Returns:: The resulting image after applying the filter
Return type:: XAImage

New in version 0.1.0.

depth_of_field(focal_region: tuple[tuple[int, int], tuple[int, int]] | None = None, intensity: float = 10.0, focal_region_saturation: float = 1.5) → XAImage[source]

Applies a depth of field filter to the image, simulating a tilt & shift effect.

Parameters:

focal_region (Union[tuple[tuple[int, int], tuple[int, int]], None]) – Two points defining a line within the image to focus the effect around (pixels around the line will be in focus), or None to use the center third of the image, defaults to None
intensity (float) – Controls the amount of distance around the focal region to keep in focus. Higher values decrease the distance before the out-of-focus effect starts. Defaults to 10.0
focal_region_saturation (float) – Adjusts the saturation of the focial region. Higher values increase saturation. Defaults to 1.5 (1.5x default saturation)

Returns:

The resulting image after applying the filter

Return type:

XAImage

New in version 0.1.0.

edges(intensity: float = 1.0) → XAImage[source]

Detects the edges in the image and highlights them colorfully, blackening other areas of the image.

Parameters:: intensity (float) – The degree to which edges are highlighted. Higher is brighter. Defaults to 1.0
Returns:: The resulting image after applying the filter
Return type:: XAImage

New in version 0.1.0.

file: str: The path to the image file, if one exists

flip_horizontally() → XAImage[source]

Flips the image horizontally.

Returns:: The image object, modifications included
Return type:: XAImage

New in version 0.1.0.

flip_vertically() → XAImage[source]

Flips the image vertically.

Returns:: The image object, modifications included
Return type:: XAImage

New in version 0.1.0.

gaussian_blur(intensity: float = 10) → XAImage[source]

Blurs the image using a Gaussian filter.

Parameters:: intensity (float) – The strength of the blur effect, defaults to 10
Returns:: The resulting image after applying the filter
Return type:: XAImage

New in version 0.1.0.

get_clipboard_representation() → NSImage[source]

Gets a clipboard-codable representation of the iimage.

When the clipboard content is set to an image, the image itself, including any modifications, is added to the clipboard. Pasting will then insert the image into the active document.

Returns:: The raw NSImage object for this XAIMage
Return type:: AppKit.NSImage

New in version 0.1.0.

horizontal_stitch() → XAImage[source]

Horizontally stacks two or more images.

The first image in the list is placed at the left side of the resulting image.

Parameters:: images (Union[list[XAImage], XAImageList]) – The list of images to stitch together
Returns:: The resulting image after stitching
Return type:: XAImage

New in version 0.1.1.

invert() → XAImage[source]

Inverts the color of the image.

Returns:: The resulting image after applying the filter
Return type:: XAImage

New in version 0.1.0.

modified: bool: Whether the image data has been modified since the object was originally created

monochrome(color: XAColor, intensity: float = 1.0) → XAImage[source]

Remaps the colors of the image to shades of the specified color.

Parameters:

color (XAColor) – The color of map the image’s colors to
intensity (float) – The strength of recoloring effect. Higher values map colors to darker shades of the provided color. Defaults to 1.0

Returns:

The resulting image after applying the filter

Return type:

XAImage

New in version 0.1.0.

open() → XAImage | XAImageList[source]

Initializes one or more images from files.

Parameters:: images (Union[str, XAPath, list[Union[str, XAPath]]]) – The image(s) to open
Returns:: The newly created image object, or a list of image objects
Return type:: Union[XAImage, XAImageList]

New in version 0.1.0.

outline(threshold: float = 0.1) → XAImage[source]

Outlines detected edges within the image in black, leaving the rest transparent.

Parameters:: threshold (float) – The threshold to use when separating edge and non-edge pixels. Larger values produce thinner edge lines. Defaults to 0.1
Returns:: The resulting image after applying the filter
Return type:: XAImage

New in version 0.1.0.

pinch(center: tuple[int, int] | None = None, intensity: float = 0.5) → XAImage[source]

Creates an inward pinch distortion at the specified location within the image.

Parameters:

center (Union[tuple[int, int], None]) – The center point of the effect, or None to use the center of the image, defaults to None
intensity (float) – Controls the scale of the pinch effect. Higher values stretch pixels away from the specified center to a greater degree. Defaults to 0.5

Returns:

The resulting image after applying the distortion

Return type:

XAImage

New in version 0.1.0.

pixellate(pixel_size: float = 8.0) → XAImage[source]

Pixellates the image.

Parameters:: pixel_size (float) – The size of the pixels, defaults to 8.0
Returns:: The resulting image after applying the filter
Return type:: XAImage

New in version 0.1.0.

pointillize(point_size: float = 20.0) → XAImage[source]

Applies a pointillization filter to the image.

Parameters:: crystal_size (float) – The radius of the points, defaults to 20.0
Returns:: The resulting image after applying the filter
Return type:: XAImage

New in version 0.1.0.

reduce_noise(noise_level: float = 0.02, sharpness: float = 0.4) → XAImage[source]

Reduces noise in the image by sharpening areas with a luminance delta below the specified noise level threshold.

Parameters:

noise_level (float) – The threshold for luminance changes in an area below which will be considered noise, defaults to 0.02
sharpness (float) – The sharpness of the resulting image, defaults to 0.4

Returns:

The resulting image after applying the filter

Return type:

XAImage

New in version 0.1.0.

resize(width: int, height: int | None = None) → XAImage[source]

Resizes the image to the specified width and height.

Parameters:

width (int) – The width of the resulting image, in pixels
height (Union[int, None]) – The height of the resulting image, in pixels, or None to maintain width:height proportions, defaults to None

Returns:

The image object, modifications included

Return type:

XAImage

New in version 0.1.1.

rotate(degrees: float) → XAImage[source]

Rotates the image clockwise by the specified number of degrees.

Parameters:: degrees (float) – The number of degrees to rotate the image by
Returns:: The image object, modifications included
Return type:: XAImage

New in version 0.1.0.

save(file_path: XAPath | str | None = None)[source]

Saves the image to a file on the disk. Saves to the original file (if there was one) by default.

Parameters:: file_path (Union[XAPath, str, None]) – The path at which to save the image file. Any existing file at that location will be overwritten, defaults to None

New in version 0.1.0.

scale(scale_factor_x: float, scale_factor_y: float | None = None) → XAImage[source]

Scales the image by the specified horizontal and vertical factors.

Parameters:

scale_factor_x (float) – The factor by which to scale the image in the X dimension
scale_factor_y (Union[float, None]) – The factor by which to scale the image in the Y dimension, or None to match the horizontal factor, defaults to None

Returns:

The image object, modifications included

Return type:

XAImage

New in version 0.1.0.

sepia(intensity: float = 1.0) → XAImage[source]

Applies a sepia filter to the image; maps all colors of the image to shades of brown.

Parameters:: intensity (float) – The opacity of the sepia effect. A value of 0 will have no impact on the image. Defaults to 1.0
Returns:: The resulting image after applying the filter
Return type:: XAImage

New in version 0.1.0.

twirl(center: tuple[int, int] | None = None, radius: float = 300.0, angle: float = 3.14) → XAImage[source]

Creates a twirl distortion by rotating pixels around the specified location within the image.

Parameters:

center (Union[tuple[int, int], None]) – The center point of the effect, or None to use the center of the image, defaults to None
radius (float) – The pixel radius around the centerpoint that defines the area to apply the effect to, defaults to 300.0
angle (float) – The angle of the twirl in radians, defaults to 3.14

Returns:

The resulting image after applying the distortion

Return type:

XAImage

New in version 0.1.0.

vertical_stitch() → XAImage[source]

Vertically stacks two or more images.

The first image in the list is placed at the bottom of the resulting image.

Parameters:: images (Union[list[XAImage], XAImageList]) – The list of images to stitch together
Returns:: The resulting image after stitching
Return type:: XAImage

New in version 0.1.1.

vignette(intensity: float = 1.0) → XAImage[source]

Applies vignette shading to the corners of the image.

Parameters:: intensity (float) – The intensity of the vignette effect, defaults to 1.0
Returns:: The resulting image after applying the filter
Return type:: XAImage

New in version 0.1.0.

property xa_elem

class PyXA.XABase.XAImageList(properties: dict, filter: dict | None = None, obj_class=None)[source]

Bases: XAList, XAClipboardCodable

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

Deprecated since version 0.2.0: Use XAImage and its methods instead.

New in version 0.0.3.

Attributes:

`__annotations__`
`__module__`
`modified`	Whether the list of images has been modified since it was initialized

Methods:

`__init__`(properties[, filter, obj_class])	Creates an efficient wrapper object around a list of scriptable elements.
`additive_composition`()	Creates a composition image by adding the color values of each image in the list.
`auto_enhance`([correct_red_eye, ...])	Attempts to enhance each image in the list by applying suggested filters.
`bloom`([intensity])	Applies a bloom effect to each image in the list.
`bump`([center, radius, curvature])	Adds a concave (inward) or convex (outward) bump to each image in the list at the specified location within each image.
`comic`()	Applies a comic filter to each image in the list.
`crop`(size[, corner])	Crops each image in the list to the specified dimensions.
`crystallize`([crystal_size])	Applies a crystallization filter to each image in the list.
`depth_of_field`([focal_region, intensity, ...])	Applies a depth of field filter to each image in the list, simulating a tilt & shift effect.
`edges`([intensity])	Detects the edges in each image of the list and highlights them colorfully, blackening other areas of the images.
`extract_text`()	Extracts and returns a list of all visible text in each image of the list.
`file`()
`flip_horizontally`()	Flips each image in the list horizontally.
`flip_vertically`()	Flips each image in the list vertically.
`gaussian_blur`([intensity])	Blurs each image in the list using a Gaussian filter.
`get_clipboard_representation`()	Gets a clipboard-codable representation of each image in the list.
`horizontal_stitch`()	Horizontally stacks each image in the list.
`invert`()	Inverts the colors of each image in the list.
`monochrome`(color[, intensity])	Remaps the colors of each image in the list to shades of the specified color.
`outline`([threshold])	Outlines detected edges within each image of the list in black, leaving the rest transparent.
`overlay_image`(image[, location, size])	Overlays an image on top of each image in the list, at the specified location, with the specified size.
`overlay_text`(text[, location, font_size, ...])	Overlays text of the specified size and color at the provided location within each image of the list.
`pad`([horizontal_border_width, ...])	Pads each image in the list with the specified color; add a border around each image in the list with the specified vertical and horizontal width.
`pinch`([center, intensity])	Adds an inward pinch distortion to each image in the list at the specified location within each image.
`pixellate`([pixel_size])	Pixellates each image in the list.
`pointillize`([point_size])	Applies a pointillization filter to each image in the list.
`reduce_noise`([noise_level, sharpness])	Reduces noise in each image of the list by sharpening areas with a luminance delta below the specified noise level threshold.
`resize`(width[, height])	Resizes each image in the list to the specified width and height.
`rotate`(degrees)	Rotates each image in the list by the specified amount of degrees.
`save`(file_paths)	Saves each image to a file on the disk.
`scale`(scale_factor_x[, scale_factor_y])	Scales each image in the list by the specified horizontal and vertical factors.
`sepia`([intensity])	Applies a sepia filter to each image in the list; maps all colors of the images to shades of brown.
`show_in_preview`()	Opens each image in the list in Preview.
`subtractive_composition`()	Creates a composition image by subtracting the color values of each image in the list successively.
`twirl`([center, radius, angle])	Adds a twirl distortion to each image in the list by rotating pixels around the specified location within each image.
`vertical_stitch`()	Vertically stacks each image in the list.
`vignette`([intensity])	Applies vignette shading to the corners of each image in the list.

__annotations__ = {}

__init__(properties: dict, filter: dict | None = None, obj_class=None)[source]

Creates an efficient wrapper object around a list of scriptable elements.

Parameters:

properties (dict) – PyXA properties passed to this object for utility purposes
object_class (type, optional) – _description_, defaults to None
filter (Union[dict, None], optional) – A dictionary of properties and values to filter items by, defaults to None

Changed in version 0.0.8: The filter property is deprecated and will be removed in a future version. Use the filter() method instead.

New in version 0.0.3.

__module__ = 'PyXA.XABase'

additive_composition() → XAImage[source]

Creates a composition image by adding the color values of each image in the list.

Parameters:: images (list[XAImage]) – The images to add together
Returns:: The resulting image composition
Return type:: XAImage

New in version 0.1.0.

auto_enhance(correct_red_eye: bool = False, crop_to_features: bool = False, correct_rotation: bool = False) → XAImageList[source]

Attempts to enhance each image in the list by applying suggested filters.

Parameters:

correct_red_eye (bool, optional) – Whether to attempt red eye removal, defaults to False
crop_to_features (bool, optional) – Whether to crop the images to focus on their main features, defaults to False
correct_rotation (bool, optional) – Whether attempt perspective correction by rotating the images, defaults to False

Returns:

The list of enhanced images

Return type:

XAImageList

New in version 0.1.0.

bloom(intensity: float = 0.5) → XAImageList[source]

Applies a bloom effect to each image in the list. Softens edges and adds a glow.

Parameters:: intensity (float) – The strength of the softening and glow effects, defaults to 0.5
Returns:: The resulting images after applying the filter
Return type:: XAImageList

New in version 0.1.0.

bump(center: tuple[int, int] | None = None, radius: float = 300.0, curvature: float = 0.5) → XAImageList[source]

Adds a concave (inward) or convex (outward) bump to each image in the list at the specified location within each image.

Parameters:

center (Union[tuple[int, int], None]) – The center point of the effect, or None to use the center of the image, defaults to None
radius (float) – The radius of the bump in pixels, defaults to 300.0
curvature (float) – Controls the direction and intensity of the bump’s curvature. Positive values create convex bumps while negative values create concave bumps. Defaults to 0.5

Returns:

The resulting images after applying the distortion

Return type:

XAImageList

New in version 0.1.0.

comic() → XAImageList[source]

Applies a comic filter to each image in the list. Outlines edges and applies a color halftone effect.

Returns:: The resulting images after applying the filter
Return type:: XAImageList

New in version 0.1.0.

crop(size: tuple[int, int], corner: tuple[int, int] | None = None) → XAImageList[source]

Crops each image in the list to the specified dimensions.

Parameters:

size (tuple[int, int]) – The dimensions to crop each image to
corner (Union[tuple[int, int], None]) – The bottom-left location to crom each image from, or None to use (0, 0), defaults to None

Returns:

The list of cropped images

Return type:

XAImageList

New in version 0.1.0.

crystallize(crystal_size: float = 20.0) → XAImageList[source]

Applies a crystallization filter to each image in the list. Creates polygon-shaped color blocks by aggregating pixel values.

Parameters:: crystal_size (float) – The radius of the crystals, defaults to 20.0
Returns:: The resulting images after applying the filter
Return type:: XAImageList

New in version 0.1.0.

depth_of_field(focal_region: tuple[tuple[int, int], tuple[int, int]] | None = None, intensity: float = 10.0, focal_region_saturation: float = 1.5) → XAImageList[source]

Applies a depth of field filter to each image in the list, simulating a tilt & shift effect.

Parameters:

focal_region (Union[tuple[tuple[int, int], tuple[int, int]], None]) – Two points defining a line within each image to focus the effect around (pixels around the line will be in focus), or None to use the center third of the image, defaults to None
intensity (float) – Controls the amount of distance around the focal region to keep in focus. Higher values decrease the distance before the out-of-focus effect starts. Defaults to 10.0
focal_region_saturation (float) – Adjusts the saturation of the focial region. Higher values increase saturation. Defaults to 1.5 (1.5x default saturation)

Returns:

The resulting images after applying the filter

Return type:

XAImageList

New in version 0.1.0.

edges(intensity: float = 1.0) → XAImageList[source]

Detects the edges in each image of the list and highlights them colorfully, blackening other areas of the images.

Parameters:: intensity (float) – The degree to which edges are highlighted. Higher is brighter. Defaults to 1.0
Returns:: The resulting images after applying the filter
Return type:: XAImageList

New in version 0.1.0.

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

Extracts and returns a list of all visible text in each image of the list.

Returns:: The array of extracted text strings
Return type:: list[str]
Example:

>>> import PyXA
>>> test = PyXA.XAImage("/Users/ExampleUser/Downloads/Example.jpg")
>>> print(test.extract_text())
["HERE'S TO THE", 'CRAZY ONES', 'the MISFITS the REBELS', 'THE TROUBLEMAKERS', ...]

New in version 0.1.0.

file() → list[XAPath][source]

flip_horizontally() → XAImageList[source]

Flips each image in the list horizontally.

Returns:: The list of flipped images
Return type:: XAImageList

New in version 0.1.0.

flip_vertically() → XAImageList[source]

Flips each image in the list vertically.

Returns:: The list of flipped images
Return type:: XAImageList

New in version 0.1.0.

gaussian_blur(intensity: float = 10) → XAImageList[source]

Blurs each image in the list using a Gaussian filter.

Parameters:: intensity (float) – The strength of the blur effect, defaults to 10
Returns:: The resulting images after applying the filter
Return type:: XAImageList

New in version 0.1.0.

get_clipboard_representation() → list[AppKit.NSImage][source]

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

When the clipboard content is set to a list of image, the raw data of each image is added to the clipboard. You can then

Returns:: A list of media item file URLs
Return type:: list[NSURL]

New in version 0.0.8.

horizontal_stitch() → XAImage[source]

Horizontally stacks each image in the list.

The first image in the list is placed at the left side of the resulting image.

Returns:: The resulting image after stitching
Return type:: XAImage

New in version 0.1.0.

invert() → XAImageList[source]

Inverts the colors of each image in the list.

Returns:: The resulting images after applying the filter
Return type:: XAImageList

New in version 0.1.0.

modified: Whether the list of images has been modified since it was initialized

monochrome(color: XAColor, intensity: float = 1.0) → XAImageList[source]

Remaps the colors of each image in the list to shades of the specified color.

Parameters:

color (XAColor) – The color of map each images colors to
intensity (float) – The strength of recoloring effect. Higher values map colors to darker shades of the provided color. Defaults to 1.0

Returns:

The resulting images after applying the filter

Return type:

XAImageList

New in version 0.1.0.

outline(threshold: float = 0.1) → XAImageList[source]

Outlines detected edges within each image of the list in black, leaving the rest transparent.

Parameters:: threshold (float) – The threshold to use when separating edge and non-edge pixels. Larger values produce thinner edge lines. Defaults to 0.1
Returns:: The resulting images after applying the filter
Return type:: XAImageList

New in version 0.1.0.

overlay_image(image: XAImage, location: tuple[int, int] | None = None, size: tuple[int, int] | None = None) → XAImageList[source]

Overlays an image on top of each image in the list, at the specified location, with the specified size.

Parameters:

image (XAImage) – The image to overlay on top of each image in the list
location (Union[tuple[int, int], None]) – The bottom-left point of the overlaid image in the results, or None to use the bottom-left point of each background image, defaults to None
size (Union[tuple[int, int], None]) – The width and height of the overlaid image, or None to use the overlaid’s images existing width and height, or (-1, -1) to use the dimensions of each background images, defaults to None

Returns:

The list of images with the specified image overlaid on top of them

Return type:

XAImageList

New in version 0.1.0.

overlay_text(text: str, location: tuple[int, int] | None = None, font_size: float = 12, font_color: XAColor | None = None) → XAImageList[source]

Overlays text of the specified size and color at the provided location within each image of the list.

Parameters:

text (str) – The text to overlay onto each image of the list
location (Union[tuple[int, int], None]) – The bottom-left point of the start of the text, or None to use (5, 5), defaults to None
font_size (float) – The font size, in pixels, of the text, defaults to 12
font_color (XAColor) – The color of the text, or None to use black, defaults to None

Returns:

The list of images with the specified text overlaid on top of them

Return type:

XAImageList

New in version 0.1.0.

pad(horizontal_border_width: int = 50, vertical_border_width: int = 50, pad_color: XAColor | None = None) → XAImageList[source]

Pads each image in the list with the specified color; add a border around each image in the list with the specified vertical and horizontal width.

Parameters:

horizontal_border_width (int) – The border width, in pixels, in the x-dimension, defaults to 50
vertical_border_width (int) – The border width, in pixels, in the y-dimension, defaults to 50
pad_color (Union[XAColor, None]) – The color of the border, or None for a white border, defaults to None

Returns:

The list of padded images

Return type:

XAImageList

New in version 0.1.0.

pinch(center: tuple[int, int] | None = None, intensity: float = 0.5) → XAImageList[source]

Adds an inward pinch distortion to each image in the list at the specified location within each image.

Parameters:

center (Union[tuple[int, int], None]) – The center point of the effect, or None to use the center of the image, defaults to None
intensity (float) – Controls the scale of the pinch effect. Higher values stretch pixels away from the specified center to a greater degree. Defaults to 0.5

Returns:

The resulting images after applying the distortion

Return type:

XAImageList

New in version 0.1.0.

pixellate(pixel_size: float = 8.0) → XAImageList[source]

Pixellates each image in the list.

Parameters:: pixel_size (float) – The size of the pixels, defaults to 8.0
Returns:: The resulting images after applying the filter
Return type:: XAImageList

New in version 0.1.0.

pointillize(point_size: float = 20.0) → XAImageList[source]

Applies a pointillization filter to each image in the list.

Parameters:: crystal_size (float) – The radius of the points, defaults to 20.0
Returns:: The resulting images after applying the filter
Return type:: XAImageList

New in version 0.1.0.

reduce_noise(noise_level: float = 0.02, sharpness: float = 0.4) → XAImageList[source]

Reduces noise in each image of the list by sharpening areas with a luminance delta below the specified noise level threshold.

Parameters:

noise_level (float) – The threshold for luminance changes in an area below which will be considered noise, defaults to 0.02
sharpness (float) – The sharpness of the resulting images, defaults to 0.4

Returns:

The resulting images after applying the filter

Return type:

XAImageList

New in version 0.1.0.

resize(width: int, height: int | None = None) → XAImageList[source]

Resizes each image in the list to the specified width and height.

Parameters:

width (int) – The width of the resulting images
height (Union[int, None]) – The height of the resulting images, or None to maintain width:height proportions, defaults to None

Returns:

The list of scaled images

Return type:

XAImageList

New in version 0.1.1.

rotate(degrees: float) → XAImageList[source]

Rotates each image in the list by the specified amount of degrees.

Parameters:: degrees (float) – The number of degrees to rotate the images by
Returns:: The list of rotated images
Return type:: XAImageList

New in version 0.1.0.

save(file_paths: list[XAPath | str])[source]

Saves each image to a file on the disk.

Parameters:: file_path (Union[XAPath, str, None]) – The path at which to save the image file. Any existing file at that location will be overwritten, defaults to None

New in version 0.1.0.

scale(scale_factor_x: float, scale_factor_y: float | None = None) → XAImageList[source]

Scales each image in the list by the specified horizontal and vertical factors.

Parameters:

scale_factor_x (float) – The factor by which to scale each image in the X dimension
scale_factor_y (Union[float, None]) – The factor by which to scale each image in the Y dimension, or None to match the horizontal factor, defaults to None

Returns:

The list of scaled images

Return type:

XAImageList

New in version 0.1.0.

sepia(intensity: float = 1.0) → XAImageList[source]

Applies a sepia filter to each image in the list; maps all colors of the images to shades of brown.

Parameters:: intensity (float) – The opacity of the sepia effect. A value of 0 will have no impact on the image. Defaults to 1.0
Returns:: The resulting images after applying the filter
Return type:: XAImageList

New in version 0.1.0.

show_in_preview()[source]: Opens each image in the list in Preview.

New in version 0.1.0.

subtractive_composition() → XAImage[source]

Creates a composition image by subtracting the color values of each image in the list successively.

Parameters:: images (list[XAImage]) – The images to create the composition from
Returns:: The resulting image composition
Return type:: XAImage

New in version 0.1.0.

twirl(center: tuple[int, int] | None = None, radius: float = 300.0, angle: float = 3.14) → XAImageList[source]

Adds a twirl distortion to each image in the list by rotating pixels around the specified location within each image.

Parameters:

center (Union[tuple[int, int], None]) – The center point of the effect, or None to use the center of the image, defaults to None
radius (float) – The pixel radius around the centerpoint that defines the area to apply the effect to, defaults to 300.0
angle (float) – The angle of the twirl in radians, defaults to 3.14

Returns:

The resulting images after applying the distortion

Return type:

XAImageList

New in version 0.1.0.

vertical_stitch() → XAImage[source]

Vertically stacks each image in the list.

The first image in the list is placed at the bottom side of the resulting image.

Returns:: The resulting image after stitching
Return type:: XAImage

New in version 0.1.0.

vignette(intensity: float = 1.0) → XAImageList[source]

Applies vignette shading to the corners of each image in the list.

Parameters:: intensity (float) – The intensity of the vignette effect, defaults to 1.0
Returns:: The resulting images after applying the filter
Return type:: XAImageList

New in version 0.1.0.

class PyXA.XABase.XAList(properties: dict, object_class: type | None = None, filter: dict | None = None)[source]

Bases: XAObject

A wrapper around NSArray and NSMutableArray objects enabling fast enumeration and lazy evaluation of Objective-C objects.

New in version 0.0.3.

Attributes:

`__annotations__`
`__module__`
`first`	Retrieves the first element of the list as a wrapped PyXA object.
`last`	Retrieves the last element of the list as a wrapped PyXA object.

Methods:

`__contains__`(item)
`__getitem__`(key)
`__init__`(properties[, object_class, filter])	Creates an efficient wrapper object around a list of scriptable elements.
`__iter__`()
`__len__`()
`__repr__`()	Return repr(self).
`__reversed__`()
`at`(index)	Retrieves the element at the specified index.
`beginning_with`(property, value)	Retrieves all elements whose property value begins with the given value.
`between`(property, value1, value2)	Retrieves all elements whose property value is between the given values.
`by_property`(property, value)	Retrieves the first element whose property value matches the given value, if one exists.
`containing`(property, value)	Retrieves all elements whose property value contains the given value.
`count`(count_function)	Counts the number of entries in the list for which the provided function is True.
`ending_with`(property, value)	Retrieves all elements whose property value ends with the given value.
`equalling`(property, value)	Retrieves all elements whose property value equals the given value.
`exists`(property)	Retrieves all elements whose specified property value exists.
`extend`(ls)	Appends all elements of the supplied list to the end of this list.
`filter`(filter[, comparison_operation, ...])	Filters the list by the given parameters.
`greater_than`(property, value)	Retrieves all elements whose property value is greater than the given value.
`index`(element)	Returns the index of the first occurrence of the element in the list, or -1 if no such element exists in the list.
`insert`(element, index)	Inserts the object referenced by the provided PyXA wrapper at the specified index.
`less_than`(property, value)	Retrieves all elements whose property value is less than the given value.
`map`(function)	Applies the given function to each element in the list and returns a new `XAList` containing the results.
`not_containing`(property, value)	Retrieves all elements whose property value does not contain the given value.
`not_equalling`(property, value)	Retrieves all elements whose property value does not equal the given value.
`not_exists`(property)	Retrieves all elements whose specified property value does not exist.
`pop`([index])	Removes the object at the specified index from the list and returns it.
`push`(*elements)	Appends the object referenced by the provided PyXA wrapper to the end of the list.
`shuffle`()	Randomizes the order of objects in the list.

__annotations__ = {}

__contains__(item)[source]

__getitem__(key: int | slice)[source]

__init__(properties: dict, object_class: type | None = None, filter: dict | None = None)[source]

Creates an efficient wrapper object around a list of scriptable elements.

Parameters:

properties (dict) – PyXA properties passed to this object for utility purposes
object_class (type, optional) – _description_, defaults to None
filter (Union[dict, None], optional) – A dictionary of properties and values to filter items by, defaults to None

Changed in version 0.0.8: The filter property is deprecated and will be removed in a future version. Use the filter() method instead.

New in version 0.0.3.

__iter__()[source]

__len__()[source]

__module__ = 'PyXA.XABase'

__repr__()[source]: Return repr(self).

__reversed__()[source]

at(index: int) → XAObject[source]

Retrieves the element at the specified index.

Parameters:: index (int) – The index of the desired element
Returns:: The PyXA-wrapped element object
Return type:: XAObject

New in version 0.0.6.

beginning_with(property: str, value: str) → XAList[source]

Retrieves all elements whose property value begins with the given value.

Parameters:

property (str) – The property to match
value (str) – The value to search for

Returns:

The list of matching elements

Return type:

XAList

Example:

>>> import PyXA
>>> app = PyXA.Application("System Events")
>>> print(app.downloads_folder.files().beginning_with("name", "Example"))
<<class 'PyXA.apps.SystemEvents.XASystemEventsFileList'>['Example.png', 'ExampleImage.png', ...]>

New in version 0.1.0.

between(property: str, value1: int | float, value2: int | float) → XAList[source]

Retrieves all elements whose property value is between the given values.

Parameters:

property (str) – The property to match
value1 (Union[int, float]) – The lower-end of the range to match
value2 (Union[int, float]) – The upper-end of the range to match

Returns:

The list of matching elements

Return type:

XAList

Example:

>>> import PyXA
>>> from datetime import datetime, timedelta
>>>
>>> app = PyXA.Application("Calendar")
>>> events = app.calendars()[3].events()
>>> now = datetime.now()
>>> print(events.between("startDate", now, now + timedelta(days=1)))
<<class 'PyXA.apps.Calendar.XACalendarEventList'>['Capstone Meeting', 'Lunch with Dan']>

New in version 0.1.0.

by_property(property: str, value: Any) → XAObject[source]

Retrieves the first element whose property value matches the given value, if one exists.

Parameters:

property (str) – The property to match
value (Any) – The value to match

Returns:

The matching element, if one is found

Return type:

XAObject

Example:

>>> import PyXA
>>> app = PyXA.Application("Photos")
>>> photo = app.media_items().by_property("id", "CB24FE9F-E9DC-4A5C-A0B0-CC779B1CEDCE/L0/001")
>>> print(photo)
<<class 'PyXA.apps.PhotosApp.XAPhotosMediaItem'>id=CB24FE9F-E9DC-4A5C-A0B0-CC779B1CEDCE/L0/001>

New in version 0.0.6.

containing(property: str, value: str) → XAList[source]

Retrieves all elements whose property value contains the given value.

Parameters:

property (str) – The property to match
value (str) – The value to search for

Returns:

The list of matching elements

Return type:

XAList

Example:

>>> import PyXA
>>> app = PyXA.Application("Reminders")
>>> print(app.reminders().containing("name", "PyXA"))
<<class 'PyXA.apps.Reminders.XARemindersReminderList'>['PyXA v0.1.0 release']>

New in version 0.0.6.

count(count_function: Callable[[object], bool]) → int[source]

Counts the number of entries in the list for which the provided function is True.

Parameters:: count_function (Callable[[object], bool]) – The function to check entries against
Returns:: The number of entries for which the given function is True.
Return type:: int

New in version 0.1.0.

ending_with(property: str, value: str) → XAList[source]

Retrieves all elements whose property value ends with the given value.

Parameters:

property (str) – The property to match
value (str) – The value to search for

Returns:

The list of matching elements

Return type:

XAList

Example:

>>> import PyXA
>>> app = PyXA.Application("System Events")
>>> print(app.downloads_folder.files().ending_with("name", ".png"))
<<class 'PyXA.apps.SystemEvents.XASystemEventsFileList'>['Example.png', 'Image.png', ...]>

New in version 0.1.0.

equalling(property: str, value: str) → XAList[source]

Retrieves all elements whose property value equals the given value.

Parameters:

property (str) – The property to match
value (str) – The value to search for

Returns:

The list of matching elements

Return type:

XAList

Example:

>>> import PyXA
>>> app = PyXA.Application("TV")
>>> print(app.tracks().equalling("playedCount", 0))
<<class 'PyXA.apps.TV.XATVTrackList'>['Frozen', 'Sunshine', 'The Hunger Games: Mockingjay - Part 2', ...]>

New in version 0.1.0.

exists(property: str) → XAList[source]

Retrieves all elements whose specified property value exists.

Parameters:: property (str) – The property to check the existence of
Returns:: The list of matching elements
Return type:: XAList

New in version 0.2.2.

extend(ls: XAList | list)[source]

Appends all elements of the supplied list to the end of this list.

Parameters:: ls (Union[XAList, list]) – _description_

New in version 0.1.1.

filter(filter: str, comparison_operation: str | None = None, value1: Any | None = None, value2: Any | None = None) → XAList[source]

Filters the list by the given parameters.

The filter may be either a format string, used to create an NSPredicate, or up to 4 arguments specifying the filtered property name, the comparison operation, and up to two values to compare against.

Parameters:

filter (str) – A format string or a property name
comparison_operation (Union[str, None], optional) – The symbol or name of a comparison operation, such as > or <, defaults to None
value1 (Union[Any, None], optional) – The first value to compare each list item’s property value against, defaults to None
value2 (Union[Any, None], optional) – The second value to compare each list item’s property value against, defaults to None

Returns:

The filtered XAList object

Return type:

XAList

Example 1:

Get the last file sent by you (via this machine) in Messages.app

>>> import PyXA
>>> app = PyXA.Application("Messages")
>>> last_file_transfer = app.file_transfers().filter("direction", "==", app.MessageDirection.OUTGOING)[-1]
>>> print(last_file_transfer)
<<class 'PyXA.apps.Messages.XAMessagesFileTransfer'>Test.jpg>

Example 2:: Get the list of favorite photos/videos from Photos.app

>>> import PyXA
>>> app = PyXA.Application("Photos")
>>> favorites = app.media_items().filter("favorite", "==", True)
>>> print(favorites)
<<class 'PyXA.apps.PhotosApp.XAPhotosMediaItemList'>['CB24FE9F-E9DC-4A5C-A0B0-CC779B1CEDCE/L0/001', 'EFEB7F37-8373-4972-8E43-21612F597185/L0/001', ...]>

Note

For properties that appear to be boolean but fail to return expected filter results, try using the corresponding 0 or 1 value instead.

Example 3:: Provide a custom format string

>>> import PyXA
>>> app = PyXA.Application("Photos")
>>> photo = app.media_items().filter("id == 'CB24FE9F-E9DC-4A5C-A0B0-CC779B1CEDCE/L0/001'")[0]
>>> print(photo)
<<class 'PyXA.apps.PhotosApp.XAPhotosMediaItem'>id=CB24FE9F-E9DC-4A5C-A0B0-CC779B1CEDCE/L0/001>

Example 4:: Get All Top-Level Playlists in Music.app

>>> import PyXA
>>> app = PyXA.Music()
>>> top_level_playlists = app.playlists().filter("parent", "!exists")
>>> print(top_level_playlists)

New in version 0.0.8.

property first: XAObject

Retrieves the first element of the list as a wrapped PyXA object.

Returns:: The wrapped object
Return type:: XAObject

New in version 0.0.3.

greater_than(property: str, value: int | float) → XAList[source]

Retrieves all elements whose property value is greater than the given value.

Parameters:

property (str) – The property to match
value (Union[int, float]) – The value to compare against

Returns:

The list of matching elements

Return type:

XAList

Example:

>>> import PyXA
>>> app = PyXA.Application("Photos")
>>> print(app.media_items().greater_than("altitude", 10000)[0].spotlight())
<<class 'PyXA.apps.PhotosApp.XAPhotosMediaItem'>id=53B0F28E-0B39-446B-896C-484CD0DC2D3C/L0/001>

New in version 0.1.0.

index(element: XAObject) → int[source]: Returns the index of the first occurrence of the element in the list, or -1 if no such element exists in the list.

New in version 0.1.2.

insert(element: XAObject, index: int)[source]: Inserts the object referenced by the provided PyXA wrapper at the specified index.

New in version 0.0.3.

property last: XAObject

Retrieves the last element of the list as a wrapped PyXA object.

Returns:: The wrapped object
Return type:: XAObject

New in version 0.0.3.

less_than(property: str, value: int | float) → XAList[source]

Retrieves all elements whose property value is less than the given value.

Parameters:

property (str) – The property to match
value (Union[int, float]) – The value to compare against

Returns:

The list of matching elements

Return type:

XAList

Example:

>>> app = PyXA.Application("Music")
>>> tracks = app.tracks()
>>> print(tracks.less_than("playedCount", 5).name())
['Outrunning Karma', 'Death of a Hero', '1994', 'Mind Is a Prison']

New in version 0.1.0.

map(function: Callable[[object], object]) → XAList[source]

Applies the given function to each element in the list and returns a new XAList containing the results.

This is most effective when the function does not access the element’s properties, as this will cause the element to be fully dereferenced. In such cases, it is better (faster) to use subclass-specific fast-enumeration methods. Use this method to associate element references with other data, e.g. by wrapping each element in a dictionary.

Parameters:: function (Callable[[object], object]) – The function to apply to each element
Returns:: The new list containing the results of the function
Return type:: XAList
Example:

>>> import PyXA
>>> app = PyXA.Application("Notes")
>>> notes = app.notes()
>>> indexed_notes = notes.map(lambda element, index: {"element": element, "id": index})
>>> print(indexed_notes[0])
{'element': <<class 'PyXA.apps.Notes.XANote'>Example Note, x-coredata://314D805E-C349-42A0-96EC-380EE21392E2/ICNote/p9527>, 'id': 0}

New in version 0.3.0.

not_containing(property: str, value: str) → XAList[source]

Retrieves all elements whose property value does not contain the given value.

Parameters:

property (str) – The property to match
value (str) – The value to search for

Returns:

The list of matching elements

Return type:

XAList

Example:

>>> import PyXA
>>> app = PyXA.Application("Reminders")
>>> print(app.reminders().not_containing("name", " "))
<<class 'PyXA.apps.Reminders.XARemindersReminderList'>['Trash', 'Thing', 'Reminder', ...]>

New in version 0.1.0.

not_equalling(property: str, value: str) → XAList[source]

Retrieves all elements whose property value does not equal the given value.

Parameters:

property (str) – The property to match
value (str) – The value to search for

Returns:

The list of matching elements

Return type:

XAList

Example:

>>> import PyXA
>>> app = PyXA.Application("TV")
>>> print(app.tracks().not_equalling("playedCount", 0))
<<class 'PyXA.apps.TV.XATVTrackList'>['The Avatar State', 'The Cave of Two Lovers', 'Return to Omashu', ...]>

New in version 0.1.0.

not_exists(property: str) → XAList[source]

Retrieves all elements whose specified property value does not exist.

Parameters:: property (str) – The property to check the non-existence of
Returns:: The list of matching elements
Return type:: XAList

New in version 0.2.2.

pop(index: int = -1) → XAObject[source]: Removes the object at the specified index from the list and returns it.

New in version 0.0.3.

push(*elements: list[XAObject]) → XAObject | list[XAObject] | None[source]: Appends the object referenced by the provided PyXA wrapper to the end of the list.

New in version 0.0.3.

shuffle() → XAList[source]

Randomizes the order of objects in the list.

Returns:: A reference to the shuffled XAList
Return type:: XAList

New in version 0.0.3.

class PyXA.XABase.XALocalDomainObject(properties)[source]

Bases: XADomain

The local domain in the file system.

New in version 0.1.0.

Attributes:

`__annotations__`
`__module__`

Methods:

__init__(properties)

Instantiates a PyXA scripting object.

__annotations__ = {}

__init__(properties)[source]

Instantiates a PyXA scripting object.

Parameters:: properties (dict, optional) – A dictionary of properties to assign to this object.

Changed in version 0.0.3: Removed on-the-fly creation of class attributes. All objects should concretely define their properties.

New in version 0.0.1.

__module__ = 'PyXA.XABase'

class PyXA.XABase.XALocation(raw_value=None, title: str | None = None, latitude: float = 0, longitude: float = 0, altitude: float | None = None, radius: int = 0, address: str | None = None)[source]

Bases: XAObject

A location with a latitude and longitude, along with other data.

New in version 0.0.2.

Attributes:

`__annotations__`
`__module__`
`address`	The address of the location
`altitude`	The altitude of the location
`current_location`	The current location of the device
`latitude`	The latitude of the location
`longitude`	The longitude of the location
`radius`	The horizontal accuracy of the location measurement
`raw_value`	The raw CLLocation object
`title`	The name of the location

Methods:

`__init__`([raw_value, title, latitude, ...])	Instantiates a PyXA scripting object.
`__repr__`()	Return repr(self).
`reverse_geocode`()	Obtains reverse-geocode information from the location's latitude and longitude.
`show_in_maps`()	Shows the location in Maps.app.

__annotations__ = {'current_location': 'XALocation'}

__init__(raw_value=None, title: str | None = None, latitude: float = 0, longitude: float = 0, altitude: float | None = None, radius: int = 0, address: str | None = None)[source]

Instantiates a PyXA scripting object.

Parameters:: properties (dict, optional) – A dictionary of properties to assign to this object.

Changed in version 0.0.3: Removed on-the-fly creation of class attributes. All objects should concretely define their properties.

New in version 0.0.1.

__module__ = 'PyXA.XABase'

__repr__()[source]: Return repr(self).

address: The address of the location

altitude: The altitude of the location

property current_location: XALocation: The current location of the device

latitude: The latitude of the location

longitude: The longitude of the location

radius: The horizontal accuracy of the location measurement

property raw_value: The raw CLLocation object

reverse_geocode() → dict[str, str][source]

Obtains reverse-geocode information from the location’s latitude and longitude.

Returns:: A dictionary containing the location’s name, street address, locality, state, country, timezone, and notable features.
Return type:: dict[str, str]
Example:

>>> import PyXA
>>> loc = PyXA.XALocation(latitude=44.460552, longitude=-110.82807)
>>> print(loc.reverse_geocode())
{'name': 'Old Faithful', 'street_number': None, 'street': 'Upper Geyser Basin Trail', 'sub_locality': None, 'locality': 'Alta', 'county': 'Teton County', 'state': 'WY', 'postal_code': '83414', 'country': 'United States', 'timezone': America/Denver (MST) offset -25200, 'notable_features': (
    "Old Faithful",
    "Yellowstone National Park"
)}

New in version 0.1.1.

show_in_maps()[source]: Shows the location in Maps.app.

New in version 0.0.6.

title: The name of the location

class PyXA.XABase.XAMenu(menu_items: list[Any], title: str = 'Select Item', prompt: str = 'Select an item', default_items: list[str] | None = None, ok_button_name: str = 'Okay', cancel_button_name: str = 'Cancel', multiple_selections_allowed: bool = False, empty_selection_allowed: bool = False)[source]

Bases: XAObject

A custom list item selection menu.

New in version 0.0.8.

Attributes:

`__annotations__`
`__module__`
`default_items`	The items to initially select
`empty_selection_allowed`	Whether the user can click OK without selecting anything
`menu_items`	The items the user can choose from
`ok_button_name`	The name of the OK button
`prompt`	The prompt to display in the dialog box
`title`	The title of the dialog window

Methods:

`__init__`(menu_items[, title, prompt, ...])	Instantiates a PyXA scripting object.
`display`()	Displays the menu, waits for the user to select an option or cancel, then returns the selected value or False if cancelled.

__annotations__ = {'cancel_button_name': 'str', 'default_items': 'list[str]', 'empty_selection_allowed': 'bool', 'menu_items': 'list[Union[str, int]]', 'multiple_selections_allowed': 'bool', 'ok_button_name': 'str', 'prompt': 'str', 'title': 'str'}

__init__(menu_items: list[Any], title: str = 'Select Item', prompt: str = 'Select an item', default_items: list[str] | None = None, ok_button_name: str = 'Okay', cancel_button_name: str = 'Cancel', multiple_selections_allowed: bool = False, empty_selection_allowed: bool = False)[source]

Instantiates a PyXA scripting object.

Parameters:: properties (dict, optional) – A dictionary of properties to assign to this object.

Changed in version 0.0.3: Removed on-the-fly creation of class attributes. All objects should concretely define their properties.

New in version 0.0.1.

__module__ = 'PyXA.XABase'

cancel_button_name: str

default_items: list[str]: The items to initially select

display() → str | int | bool | list[str] | list[int][source]

Displays the menu, waits for the user to select an option or cancel, then returns the selected value or False if cancelled.

Returns:: The selected value or False if no value was selected
Return type:: Union[str, int, bool, list[str], list[int]]

New in version 0.0.8.

empty_selection_allowed: bool: Whether the user can click OK without selecting anything

menu_items: list[str | int]: The items the user can choose from

multiple_selections_allowed: bool

ok_button_name: str: The name of the OK button

prompt: str: The prompt to display in the dialog box

title: str: The title of the dialog window

class PyXA.XABase.XANetworkDomainObject(properties)[source]

Bases: XADomain

The network domain in the file system.

New in version 0.1.0.

Attributes:

`__annotations__`
`__module__`

Methods:

__init__(properties)

Instantiates a PyXA scripting object.

__annotations__ = {}

__init__(properties)[source]

Instantiates a PyXA scripting object.

Parameters:: properties (dict, optional) – A dictionary of properties to assign to this object.

Changed in version 0.0.3: Removed on-the-fly creation of class attributes. All objects should concretely define their properties.

New in version 0.0.1.

__module__ = 'PyXA.XABase'

class PyXA.XABase.XAObject(properties: dict | None = None)[source]

Bases: object

A general class for PyXA scripting objects.

See also

XABaseScriptable.XASBObject

New in version 0.0.1.

Attributes:

`__annotations__`
`__dict__`
`__hash__`
`__module__`
`__weakref__`	list of weak references to the object (if defined)
`xa_estr`
`xa_sevt`
`xa_wksp`

Methods:

`__eq__`(other)	Return self==value.
`__init__`([properties])	Instantiates a PyXA scripting object.
`exists`()	Returns true if the scripting object referenced by this PyXA object exists, false otherwise.
`set_properties`(properties)	Updates the value of multiple properties of the scripting element associated with this object.
`set_property`(property_name, value)	Updates the value of a single property of the scripting element associated with this object.

__annotations__ = {}

__dict__ = mappingproxy({'__module__': 'PyXA.XABase', '__doc__': 'A general class for PyXA scripting objects.\n\n .. seealso:: :class:`XABaseScriptable.XASBObject`\n\n .. versionadded:: 0.0.1\n ', '_xa_sevt': None, '_xa_estr': None, '_xa_wksp': None, '__init__': <function XAObject.__init__>, 'xa_wksp': <property object>, 'xa_sevt': <property object>, 'xa_estr': <property object>, '_exec_suppresed': <function XAObject._exec_suppresed>, '_new_element': <function XAObject._new_element>, '_spawn_thread': <function XAObject._spawn_thread>, 'set_properties': <function XAObject.set_properties>, 'set_property': <function XAObject.set_property>, 'exists': <function XAObject.exists>, '__eq__': <function XAObject.__eq__>, '__dict__': <attribute '__dict__' of 'XAObject' objects>, '__weakref__': <attribute '__weakref__' of 'XAObject' objects>, '__hash__': None, '__annotations__': {}})

__eq__(other: XAObject)[source]: Return self==value.

__hash__ = None

__init__(properties: dict | None = None)[source]

Instantiates a PyXA scripting object.

Parameters:: properties (dict, optional) – A dictionary of properties to assign to this object.

Changed in version 0.0.3: Removed on-the-fly creation of class attributes. All objects should concretely define their properties.

New in version 0.0.1.

__module__ = 'PyXA.XABase'

__weakref__: list of weak references to the object (if defined)

exists() → bool[source]

Returns true if the scripting object referenced by this PyXA object exists, false otherwise.

Returns:: True if the scripting object exists
Return type:: bool

New in version 0.2.2.

set_properties(properties: dict) → XAObject[source]

Updates the value of multiple properties of the scripting element associated with this object.

Parameters:: properties (dict) – A dictionary defining zero or more property names and updated values as key-value pairs.
Returns:: A reference to this PyXA object.
Return type:: XAObject

Deprecated since version 0.2.0: Use set_property() instead.

New in version 0.0.1.

set_property(property_name: str, value: Any) → XAObject[source]

Updates the value of a single property of the scripting element associated with this object.

Parameters:

property (str) – The name of the property to assign a new value to.
value (Any) – The value to assign to the specified property.

Returns:

A reference to this PyXA object.

Return type:

XAObject

New in version 0.0.1.

property xa_estr

property xa_sevt

property xa_wksp

class PyXA.XABase.XAParagraph(properties)[source]

Bases: XAText

A class for managing and interacting with paragraphs in text documents.

New in version 0.0.1.

Attributes:

`__annotations__`
`__module__`

Methods:

__init__(properties)

Instantiates a PyXA scripting object.

__annotations__ = {'color': 'XAColor', 'font': 'str', 'size': 'int', 'text': 'str'}

__init__(properties)[source]

Instantiates a PyXA scripting object.

Parameters:: properties (dict, optional) – A dictionary of properties to assign to this object.

Changed in version 0.0.3: Removed on-the-fly creation of class attributes. All objects should concretely define their properties.

New in version 0.0.1.

__module__ = 'PyXA.XABase'

class PyXA.XABase.XAParagraphList(properties: dict, filter: dict | None = None)[source]

Bases: XATextList

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

New in version 0.0.5.

Attributes:

`__annotations__`
`__module__`

Methods:

__init__(properties[, filter])

Creates an efficient wrapper object around a list of scriptable elements.

__annotations__ = {}

__init__(properties: dict, filter: dict | None = None)[source]

Creates an efficient wrapper object around a list of scriptable elements.

Parameters:

properties (dict) – PyXA properties passed to this object for utility purposes
object_class (type, optional) – _description_, defaults to None
filter (Union[dict, None], optional) – A dictionary of properties and values to filter items by, defaults to None

Changed in version 0.0.8: The filter property is deprecated and will be removed in a future version. Use the filter() method instead.

New in version 0.0.3.

__module__ = 'PyXA.XABase'

class PyXA.XABase.XAPath(path: str | NSURL)[source]

Bases: XAObject, XAClipboardCodable

A path to a file on the disk.

New in version 0.0.5.

Attributes:

`__annotations__`
`__hash__`
`__module__`
`name`	The name of the file or folder at the path.
`path`	The path string without the file:// prefix
`url`	The path string with the file:// prefix included

Methods:

`__eq__`(other)	Return self==value.
`__init__`(path)	Instantiates a PyXA scripting object.
`__repr__`()	Return repr(self).
`get_clipboard_representation`()	Gets a clipboard-codable representation of the path.
`open`()	Opens the file in its default application.
`select`()	Opens a Finder window showing the folder containing this path, with the associated file selected.
`show_in_finder`()	Opens a Finder window showing the folder containing this path, with the associated file selected.

__annotations__ = {}

__eq__(other: XAPath)[source]: Return self==value.

__hash__ = None

__init__(path: str | NSURL)[source]

Instantiates a PyXA scripting object.

Parameters:: properties (dict, optional) – A dictionary of properties to assign to this object.

Changed in version 0.0.3: Removed on-the-fly creation of class attributes. All objects should concretely define their properties.

New in version 0.0.1.

__module__ = 'PyXA.XABase'

__repr__()[source]: Return repr(self).

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

Gets a clipboard-codable representation of the path.

When the clipboard content is set to a path, the raw file URL data and the string representation of the path are added to the clipboard.

Returns:: The clipboard-codable form of the path
Return type:: Any

New in version 0.0.8.

property name: str: The name of the file or folder at the path.

open()[source]: Opens the file in its default application.

path: The path string without the file:// prefix

select()[source]: Opens a Finder window showing the folder containing this path, with the associated file selected. Synonymous with show_in_finder().

show_in_finder()[source]: Opens a Finder window showing the folder containing this path, with the associated file selected. Synonymous with select().

url: The path string with the file:// prefix included

class PyXA.XABase.XAPredicate[source]

Bases: XAObject, XAClipboardCodable

A predicate used to filter arrays.

New in version 0.0.4.

Attributes:

`__annotations__`
`__module__`

Methods:

`__init__`()	Instantiates a PyXA scripting object.
`add_begins_with_condition`(property, value)	Appends a BEGINSWITH condition to the end of the predicate format.
`add_between_condition`(property, value1, value2)	Appends a BETWEEN condition to the end of the predicate format.
`add_contains_condition`(property, value)	Appends a CONTAINS condition to the end of the predicate format.
`add_ends_with_condition`(property, value)	Appends a ENDSWITH condition to the end of the predicate format.
`add_eq_condition`(property, value)	Appends an == condition to the end of the predicate format.
`add_geq_condition`(property, value)	Appends a >= condition to the end of the predicate format.
`add_gt_condition`(property, value)	Appends a > condition to the end of the predicate format.
`add_leq_condition`(property, value)	Appends a <= condition to the end of the predicate format.
`add_lt_condition`(property, value)	Appends a < condition to the end of the predicate format.
`add_match_condition`(property, value)	Appends a MATCHES condition to the end of the predicate format.
`add_neq_condition`(property, value)	Appends a != condition to the end of the predicate format.
`evaluate`(target)	Evaluates the predicate on the given array.
`evaluate_with_dict`(properties_dict)	Evaluates the specified array against a predicate constructed from the supplied dictionary.
`evaluate_with_format`(fmt, *fmt_parameters)	Evaluates the specified array against a predicate with the given format.
`from_args`(*args)	Populates the XAPredicate object from the supplied key, value argument pairs.
`from_dict`(ref_dict)	Populates the XAPredicate object from the supplied dictionary.
`get_clipboard_representation`()	Gets a clipboard-codable representation of the predicate.
`insert_begins_with_condition`(index, ...)	Inserts a BEGINSWITH condition to the predicate format at the desired location, specified by index.
`insert_between_condition`(index, property, ...)	Inserts a BETWEEN condition to the predicate format at the desired location, specified by index.
`insert_contains_condition`(index, property, value)	Inserts a CONTAINS condition to the predicate format at the desired location, specified by index.
`insert_ends_with_condition`(index, property, ...)	Inserts a ENDSWITH condition to the predicate format at the desired location, specified by index.
`insert_eq_condition`(index, property, value)	Inserts an == condition to the predicate format at the desired location, specified by index.
`insert_geq_condition`(index, property, value)	Inserts a >= condition to the predicate format at the desired location, specified by index.
`insert_gt_condition`(index, property, value)	Inserts a > condition to the predicate format at the desired location, specified by index.
`insert_leq_condition`(index, property, value)	Inserts a <= condition to the predicate format at the desired location, specified by index.
`insert_lt_condition`(index, property, value)	Inserts a < condition to the predicate format at the desired location, specified by index.
`insert_match_condition`(index, property, value)	Inserts a MATCHES condition to the predicate format at the desired location, specified by index.
`insert_neq_condition`(index, property, value)	Inserts a != condition to the predicate format at the desired location, specified by index.

__annotations__ = {'keys': 'list[str]', 'operators': 'list[str]', 'values': 'list[str]'}

__init__()[source]

Instantiates a PyXA scripting object.

Parameters:: properties (dict, optional) – A dictionary of properties to assign to this object.

Changed in version 0.0.3: Removed on-the-fly creation of class attributes. All objects should concretely define their properties.

New in version 0.0.1.

__module__ = 'PyXA.XABase'

add_begins_with_condition(property: str, value: Any)[source]

Appends a BEGINSWITH condition to the end of the predicate format.

The added condition will have the form property BEGINSWITH value.

Parameters:

property (str) – A property of an object to check the condition against
value (Any) – The target value of the condition

New in version 0.0.4.

add_between_condition(property: str, value1: int | float, value2: int | float)[source]

Appends a BETWEEN condition to the end of the predicate format.

The added condition will have the form property BETWEEN [value1, value2].

Parameters:

property (str) – A property of an object to check the condition against
value1 (Union[int, float]) – The lower target value of the condition
value2 (Union[int, float]) – The upper target value of the condition

New in version 0.0.4.

add_contains_condition(property: str, value: Any)[source]

Appends a CONTAINS condition to the end of the predicate format.

The added condition will have the form property CONTAINS value.

Parameters:

property (str) – A property of an object to check the condition against
value (Any) – The target value of the condition

New in version 0.0.4.

add_ends_with_condition(property: str, value: Any)[source]

Appends a ENDSWITH condition to the end of the predicate format.

The added condition will have the form property ENDSWITH value.

Parameters:

property (str) – A property of an object to check the condition against
value (Any) – The target value of the condition

New in version 0.0.4.

add_eq_condition(property: str, value: Any)[source]

Appends an == condition to the end of the predicate format.

The added condition will have the form property == value.

Parameters:

property (str) – A property of an object to check the condition against
value (Any) – The target value of the condition

New in version 0.0.4.

add_geq_condition(property: str, value: Any)[source]

Appends a >= condition to the end of the predicate format.

The added condition will have the form property >= value.

Parameters:

property (str) – A property of an object to check the condition against
value (Any) – The target value of the condition

New in version 0.0.4.

add_gt_condition(property: str, value: Any)[source]

Appends a > condition to the end of the predicate format.

The added condition will have the form property > value.

Parameters:

property (str) – A property of an object to check the condition against
value (Any) – The target value of the condition

New in version 0.0.4.

add_leq_condition(property: str, value: Any)[source]

Appends a <= condition to the end of the predicate format.

The added condition will have the form property <= value.

Parameters:

property (str) – A property of an object to check the condition against
value (Any) – The target value of the condition

New in version 0.0.4.

add_lt_condition(property: str, value: Any)[source]

Appends a < condition to the end of the predicate format.

The added condition will have the form property < value.

Parameters:

property (str) – A property of an object to check the condition against
value (Any) – The target value of the condition

New in version 0.0.4.

add_match_condition(property: str, value: Any)[source]

Appends a MATCHES condition to the end of the predicate format.

The added condition will have the form property MATCHES value.

Parameters:

property (str) – A property of an object to check the condition against
value (Any) – The target value of the condition

New in version 0.0.4.

add_neq_condition(property: str, value: Any)[source]

Appends a != condition to the end of the predicate format.

The added condition will have the form property != value.

Parameters:

property (str) – A property of an object to check the condition against
value (Any) – The target value of the condition

New in version 0.0.4.

evaluate(target: NSArray | XAList) → NSArray[source]

Evaluates the predicate on the given array.

Parameters:: target (AppKit.NSArray) – The array to evaluate against the predicate
Returns:: The filtered array
Return type:: AppKit.NSArray

New in version 0.0.4.

evaluate_with_dict(properties_dict: dict) → NSArray[source]

Evaluates the specified array against a predicate constructed from the supplied dictionary.

The predicate will use == for all comparisons.

Parameters:

target (AppKit.NSArray) – The array to filter
properties_dict (dict) – The specification of key, value pairs

Returns:

The filtered array

Return type:

AppKit.NSArray

New in version 0.0.4.

evaluate_with_format(fmt: str, *fmt_parameters) → NSArray[source]

Evaluates the specified array against a predicate with the given format.

Parameters:

target (AppKit.NSArray) – The array to filter
fmt (str) – The format string for the predicate
fmt_parameters (Any) – The parameters for the format string

Returns:

The filtered array

Return type:

AppKit.NSArray

Changed in version 0.3.0: Added the fmt_parameters parameter.

New in version 0.0.4.

from_args(*args) → XAPredicate[source]

Populates the XAPredicate object from the supplied key, value argument pairs.

The number of keys and values must be equal. The predicate will use == for all comparisons.

Raises:: InvalidPredicateError – Raised when the number of keys does not match the number of values
Returns:: The populated predicate object
Return type:: XAPredicate

New in version 0.0.4.

from_dict(ref_dict: dict) → XAPredicate[source]

Populates the XAPredicate object from the supplied dictionary.

The predicate will use == for all comparisons.

Parameters:: ref_dict (dict) – A specification of key, value pairs
Returns:: The populated predicate object
Return type:: XAPredicate

New in version 0.0.4.

get_clipboard_representation() → str[source]

Gets a clipboard-codable representation of the predicate.

When a predicate is copied to the clipboard, the string representation of the predicate is added to the clipboard.

Returns:: The string representation of the predicate
Return type:: str

New in version 0.0.8.

insert_begins_with_condition(index: int, property: str, value: Any)[source]

Inserts a BEGINSWITH condition to the predicate format at the desired location, specified by index.

The added condition will have the form property BEGINSWITH value.

Parameters:

property (str) – A property of an object to check the condition against
value (Any) – The target value of the condition

New in version 0.0.4.

insert_between_condition(index: int, property: str, value1: int | float, value2: int | float)[source]

Inserts a BETWEEN condition to the predicate format at the desired location, specified by index.

The added condition will have the form property BETWEEN [value1, value2].

Parameters:

property (str) – A property of an object to check the condition against
value1 (Union[int, float]) – The lower target value of the condition
value2 – The upper target value of the condition

New in version 0.0.4.

insert_contains_condition(index: int, property: str, value: Any)[source]

Inserts a CONTAINS condition to the predicate format at the desired location, specified by index.

The added condition will have the form property CONTAINS value.

Parameters:

property (str) – A property of an object to check the condition against
value (Any) – The target value of the condition

New in version 0.0.4.

insert_ends_with_condition(index: int, property: str, value: Any)[source]

Inserts a ENDSWITH condition to the predicate format at the desired location, specified by index.

The added condition will have the form property ENDSWITH value.

Parameters:

property (str) – A property of an object to check the condition against
value (Any) – The target value of the condition

New in version 0.0.4.

insert_eq_condition(index: int, property: str, value: Any)[source]

Inserts an == condition to the predicate format at the desired location, specified by index.

The added condition will have the form property == value.

Parameters:

property (str) – A property of an object to check the condition against
value (Any) – The target value of the condition

New in version 0.0.4.

insert_geq_condition(index: int, property: str, value: Any)[source]

Inserts a >= condition to the predicate format at the desired location, specified by index.

The added condition will have the form property >= value.

Parameters:

property (str) – A property of an object to check the condition against
value (Any) – The target value of the condition

New in version 0.0.4.

insert_gt_condition(index: int, property: str, value: Any)[source]

Inserts a > condition to the predicate format at the desired location, specified by index.

The added condition will have the form property > value.

Parameters:

property (str) – A property of an object to check the condition against
value (Any) – The target value of the condition

New in version 0.0.4.

insert_leq_condition(index: int, property: str, value: Any)[source]

Inserts a <= condition to the predicate format at the desired location, specified by index.

The added condition will have the form property <= value.

Parameters:

property (str) – A property of an object to check the condition against
value (Any) – The target value of the condition

New in version 0.0.4.

insert_lt_condition(index: int, property: str, value: Any)[source]

Inserts a < condition to the predicate format at the desired location, specified by index.

The added condition will have the form property < value.

Parameters:

property (str) – A property of an object to check the condition against
value (Any) – The target value of the condition

New in version 0.0.4.

insert_match_condition(index: int, property: str, value: Any)[source]

Inserts a MATCHES condition to the predicate format at the desired location, specified by index.

The added condition will have the form property MATCHES value.

Parameters:

property (str) – A property of an object to check the condition against
value (Any) – The target value of the condition

New in version 0.0.4.

insert_neq_condition(index: int, property: str, value: Any)[source]

Inserts a != condition to the predicate format at the desired location, specified by index.

The added condition will have the form property != value.

Parameters:

property (str) – A property of an object to check the condition against
value (Any) – The target value of the condition

New in version 0.0.4.

keys: list[str]

operators: list[str]

values: list[str]

class PyXA.XABase.XASentence(properties)[source]

Bases: XAText

A class for managing and interacting with sentences in text documents.

New in version 0.0.1.

Attributes:

`__annotations__`
`__module__`

Methods:

__init__(properties)

Instantiates a PyXA scripting object.

__annotations__ = {'color': 'XAColor', 'font': 'str', 'size': 'int', 'text': 'str'}

__init__(properties)[source]

Instantiates a PyXA scripting object.

Parameters:: properties (dict, optional) – A dictionary of properties to assign to this object.

Changed in version 0.0.3: Removed on-the-fly creation of class attributes. All objects should concretely define their properties.

New in version 0.0.1.

__module__ = 'PyXA.XABase'

class PyXA.XABase.XASentenceList(properties: dict, filter: dict | None = None)[source]

Bases: XATextList

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

New in version 0.0.5.

Attributes:

`__annotations__`
`__module__`

Methods:

__init__(properties[, filter])

Creates an efficient wrapper object around a list of scriptable elements.

__annotations__ = {}

__init__(properties: dict, filter: dict | None = None)[source]

Creates an efficient wrapper object around a list of scriptable elements.

Parameters:

properties (dict) – PyXA properties passed to this object for utility purposes
object_class (type, optional) – _description_, defaults to None
filter (Union[dict, None], optional) – A dictionary of properties and values to filter items by, defaults to None

Changed in version 0.0.8: The filter property is deprecated and will be removed in a future version. Use the filter() method instead.

New in version 0.0.3.

__module__ = 'PyXA.XABase'

class PyXA.XABase.XASound(sound_reference: str | XAURL | XAPath)[source]

Bases: XAObject, XAClipboardCodable

A class for playing and interacting with audio files and data.

New in version 0.0.1.

Attributes:

`__annotations__`
`__module__`
`duration`	The duration of the sound in seconds
`num_sample_frames`	The number of sample frames in the audio file.
`sample_rate`	The sample rate for the sound format, in hertz.

Methods:

`__init__`(sound_reference)	Instantiates a PyXA scripting object.
`beep`()	Plays the system Beep sound.
`get_clipboard_representation`()	Gets a clipboard-codable representation of the sound.
`loop`(times)	Plays the sound the specified number of times.
`open`()	Initializes one or more sounds from files.
`pause`()	Pauses the sound.
`play`([new_thread])	Plays the sound from the beginning.
`resume`()	Plays the sound starting from the time it was last paused at.
`save`(file_path)	Saves the sound to the specified file path.
`set_volume`(volume)	Sets the volume of the sound.
`stop`()	Stops playback of the sound and rewinds it to the beginning.
`trim`(start_time, end_time)	Trims the sound to the specified start and end time, in seconds.
`volume`()	Returns the current volume of the sound.

__annotations__ = {'duration': 'float'}

__init__(sound_reference: str | XAURL | XAPath)[source]

Instantiates a PyXA scripting object.

Parameters:: properties (dict, optional) – A dictionary of properties to assign to this object.

Changed in version 0.0.3: Removed on-the-fly creation of class attributes. All objects should concretely define their properties.

New in version 0.0.1.

__module__ = 'PyXA.XABase'

beep()[source]: Plays the system Beep sound.

New in version 0.1.0.

property duration: float: The duration of the sound in seconds

get_clipboard_representation() → list[NSSound | NSURL | str][source]

Gets a clipboard-codable representation of the sound.

When the clipboard content is set to a sound, the raw sound data, the associated file URL, and the path string of the file are added to the clipboard.

Returns:: The clipboard-codable form of the sound
Return type:: Any

New in version 0.0.8.

loop(times: int) → XASound[source]

Plays the sound the specified number of times.

Audio playback runs in a separate thread. For the sound the play properly, you must keep the main thread alive over the duration of the desired playback.

Parameters:: times (int) – The number of times to loop the sound.
Returns:: A reference to this sound object.
Return type:: XASound
Example:

>>> import PyXA
>>> import time
>>> glass_sound = PyXA.sound("Glass")
>>> glass_sound.loop(10)
>>> time.sleep(glass_sound.duration * 10)

New in version 0.0.1.

property num_sample_frames: int: The number of sample frames in the audio file.

New in version 0.1.0.

open() → XASound | XASoundList[source]

Initializes one or more sounds from files.

Parameters:: sound_references (Union[str, XAPath, list[Union[str, XAPath]]]) – The sound(s) to open
Returns:: The newly created sound object, or a list of sound objects
Return type:: Union[XASound, XASoundList]

New in version 0.1.0.

pause() → XASound[source]

Pauses the sound.

Returns:: A reference to this sound object.
Return type:: XASound
Example:

>>> import PyXA
>>> glass_sound = PyXA.sound("Glass")
>>> glass_sound.pause()

See also

resume(), stop()

New in version 0.0.1.

play(new_thread=False) → XASound[source]

Plays the sound from the beginning.

Audio playback runs in a separate thread. For the sound the play properly, you must keep the main thread alive over the duration of the desired playback.

Parameters:: new_thread (bool, optional) – Whether to play the sound in a new thread, defaults to False
Returns:: A reference to this sound object.
Return type:: XASound
Example:

>>> import PyXA
>>> import time
>>> glass_sound = PyXA.sound("Glass")
>>> glass_sound.play()
>>> time.sleep(glass_sound.duration)

See also

pause(), stop()

New in version 0.0.1.

resume() → XASound[source]

Plays the sound starting from the time it was last paused at.

Audio playback runs in a separate thread. For the sound the play properly, you must keep the main thread alive over the duration of the desired playback.

Returns:: A reference to this sound object.
Return type:: XASound
Example:

>>> import PyXA
>>> glass_sound = PyXA.sound("Glass")
>>> glass_sound.resume()

See also

pause(), play()

New in version 0.0.1.

property sample_rate: float: The sample rate for the sound format, in hertz.

New in version 0.1.0.

save(file_path: XAPath | str)[source]

Saves the sound to the specified file path.

Parameters:: file_path (Union[XAPath, str]) – The path to save the sound to

New in version 0.1.0.

set_volume(volume: float) → XASound[source]

Sets the volume of the sound.

Parameters:: volume (int) – The desired volume of the sound in the range [0.0, 1.0].
Returns:: A reference to this sound object.
Return type:: XASound
Example:

>>> import PyXA
>>> glass_sound = PyXA.sound("Glass")
>>> glass_sound.set_volume(1.0)

See also

volume()

New in version 0.0.1.

stop() → XASound[source]

Stops playback of the sound and rewinds it to the beginning.

Returns:: A reference to this sound object.
Return type:: XASound
Example:

>>> import PyXA
>>> glass_sound = PyXA.sound("Glass")
>>> glass_sound.stop()

See also

pause(), play()

New in version 0.0.1.

trim(start_time: float, end_time: float) → XASound[source]

Trims the sound to the specified start and end time, in seconds.

This will create a momentary sound data file in the current working directory for storing the intermediary trimmed sound data.

Parameters:

start_time (float) – The start time in seconds
end_time (float) – The end time in seconds

Returns:

The updated sound object

Return type:

XASound

New in version 0.1.0.

volume() → float[source]

Returns the current volume of the sound.

Returns:: The volume level of the sound.
Return type:: int
Example:

>>> import PyXA
>>> glass_sound = PyXA.sound("Glass")
>>> print(glass_sound.volume())
1.0

See also

set_volume()

New in version 0.0.1.

class PyXA.XABase.XASoundList(properties: dict, filter: dict | None = None)[source]

Bases: XAList, XAClipboardCodable

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

New in version 0.1.0.

Attributes:

`__annotations__`
`__module__`

Methods:

`__init__`(properties[, filter])	Creates an efficient wrapper object around a list of scriptable elements.
`duration`()
`file`()
`get_clipboard_representation`()	Gets a clipboard-codable representation of each sound in the list.
`num_sample_frames`()
`pause`()	Pauses playback of all sounds in the list.
`play`()	Plays all sounds in the list simultaneously.
`resume`()	Resumes playback of all sounds in the list.
`sample_rate`()
`stop`()	Stops playback of all sounds in the list.
`trim`(start_time, end_time)	Trims each sound in the list to the specified start and end time, in seconds.

__annotations__ = {}

__init__(properties: dict, filter: dict | None = None)[source]

Creates an efficient wrapper object around a list of scriptable elements.

Parameters:

properties (dict) – PyXA properties passed to this object for utility purposes
object_class (type, optional) – _description_, defaults to None
filter (Union[dict, None], optional) – A dictionary of properties and values to filter items by, defaults to None

Changed in version 0.0.8: The filter property is deprecated and will be removed in a future version. Use the filter() method instead.

New in version 0.0.3.

__module__ = 'PyXA.XABase'

duration() → list[float][source]

file() → list[XAPath][source]

get_clipboard_representation() → list[NSSound | NSURL | str][source]

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

When the clipboard content is set to a list of sounds, each sound’s raw sound data, its associated file URL, and its file path string are added to the clipboard.

Returns:: The clipboard-codable form of the sound
Return type:: Any

New in version 0.1.0.

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

pause() → XASoundList[source]

Pauses playback of all sounds in the list.

Returns:: The list of sounds.
Return type:: XASoundList

New in version 0.1.2.

play() → XASoundList[source]

Plays all sounds in the list simultaneously.

Returns:: The list of sounds.
Return type:: XASoundList

New in version 0.1.2.

resume() → XASoundList[source]

Resumes playback of all sounds in the list.

Returns:: The list of sounds.
Return type:: XASoundList

New in version 0.1.2.

sample_rate() → list[float][source]

stop() → XASoundList[source]

Stops playback of all sounds in the list.

Returns:: The list of sounds.
Return type:: XASoundList

New in version 0.1.2.

trim(start_time: float, end_time: float) → XASoundList[source]

Trims each sound in the list to the specified start and end time, in seconds.

Parameters:

start_time (float) – The start time in seconds
end_time (float) – The end time in seconds

Returns:

The list of updated sounds

Return type:

XASoundList

New in version 0.1.2.

class PyXA.XABase.XASpotlight(*query: list[Any])[source]

Bases: XAObject

A Spotlight query for files on the disk.

New in version 0.0.9.

Attributes:

`__annotations__`
`__module__`
`predicate`	The predicate to filter search results by
`query`	The query terms to search
`results`	The results of the search

Methods:

`__init__`(*query)	Instantiates a PyXA scripting object.
`run`()	Runs the search.
`show_in_finder`()	Shows the search in Finder.

__annotations__ = {'predicate': 'Union[str, XAPredicate]', 'query': 'list[Any]', 'results': 'list[XAPath]', 'timeout': 'int'}

__init__(*query: list[Any])[source]

Instantiates a PyXA scripting object.

Parameters:: properties (dict, optional) – A dictionary of properties to assign to this object.

Changed in version 0.0.3: Removed on-the-fly creation of class attributes. All objects should concretely define their properties.

New in version 0.0.1.

__module__ = 'PyXA.XABase'

predicate: str | XAPredicate: The predicate to filter search results by

query: list[Any]: The query terms to search

property results: list[XAPath]: The results of the search

run()[source]

Runs the search.

Example:

>>> import PyXA
>>> from datetime import date, datetime, time
>>> date1 = datetime.combine(date(2022, 5, 17), time(0, 0, 0))
>>> date2 = datetime.combine(date(2022, 5, 18), time(0, 0, 0))
>>> search = PyXA.XASpotlight(date1, date2)
>>> print(search.results)
[<<class 'PyXA.XAPath'>file:///Users/exampleUser/Downloads/>, <<class 'PyXA.XAPath'>file:///Users/exampleUser/Downloads/Example.txt>, ...]

New in version 0.0.9.

show_in_finder()[source]: Shows the search in Finder. This might not reveal the same search results.

New in version 0.0.9.

timeout: int

class PyXA.XABase.XASystemDomainObject(properties)[source]

Bases: XADomain

The system domain in the file system.

New in version 0.1.0.

Attributes:

`__annotations__`
`__module__`

Methods:

__init__(properties)

Instantiates a PyXA scripting object.

__annotations__ = {}

__init__(properties)[source]

Instantiates a PyXA scripting object.

Parameters:: properties (dict, optional) – A dictionary of properties to assign to this object.

Changed in version 0.0.3: Removed on-the-fly creation of class attributes. All objects should concretely define their properties.

New in version 0.0.1.

__module__ = 'PyXA.XABase'

class PyXA.XABase.XAText(properties)[source]

Bases: XAObject

A class for managing and interacting with the text of documents.

New in version 0.0.1.

Attributes:

`__annotations__`
`__module__`
`color`	The color of the first character
`font`	The name of the font of the first character
`size`	The size in points of the first character
`text`	The plaintext contents of the rich text

Methods:

`__init__`(properties)	Instantiates a PyXA scripting object.
`__len__`()
`__repr__`()	Return repr(self).
`__str__`()	Return str(self).
`attachments`([filter])	Gets a list of attachments of the text.
`attribute_runs`([filter])	Gets a list of attribute runs in the text.
`characters`([filter])	Gets a list of characters in the text.
`extract_addresses`()	Gets a list of addresses in the text.
`extract_dates`()	Gets a list of dates and durations in the text.
`extract_phone_numbers`()	Gets a list of phone numbers in the text.
`extract_urls`()	Gets a list of URLs in the text.
`paragraphs`([filter])	Gets a list of paragraphs in the text.
`sentences`()	Gets a list of sentences in the text.
`tag_entities`([unit])	Tags each word of the text with either the category of entity it represents (i.e. person, place, or organization) or its part of speech.
`tag_languages`([unit])	Tags each paragraph of the text with its language.
`tag_lemmas`([unit])	Tags each word of the text with its stem word.
`tag_parts_of_speech`([unit])	Tags each word of the text with its associated part of speech.
`tag_sentiments`([sentiment_scale, unit])	Tags each paragraph of the text with a sentiment rating.
`words`([filter])	Gets a list of words in the text.

__annotations__ = {'color': 'XAColor', 'font': 'str', 'size': 'int', 'text': 'str'}

__init__(properties)[source]

Instantiates a PyXA scripting object.

Parameters:: properties (dict, optional) – A dictionary of properties to assign to this object.

Changed in version 0.0.3: Removed on-the-fly creation of class attributes. All objects should concretely define their properties.

New in version 0.0.1.

__len__()[source]

__module__ = 'PyXA.XABase'

__repr__()[source]: Return repr(self).

__str__()[source]: Return str(self).

attachments(filter: dict | None = None) → XAAttachmentList[source]

Gets a list of attachments of the text.

Parameters:: filter (dict, optional) – The properties and associated values to filter attachments by, defaults to None
Returns:: The list of attachments
Return type:: XAAttachmentList

New in version 0.0.1.

attribute_runs(filter: dict | None = None) → XAAttributeRunList[source]

Gets a list of attribute runs in the text. For formatted text, this returns all sequences of characters sharing the same attributes.

Parameters:: filter (dict, optional) – The properties and associated values to filter attribute runs by, defaults to None
Returns:: The list of attribute runs
Return type:: XAAttributeRunList

New in version 0.0.1.

characters(filter: dict | None = None) → XACharacterList[source]

Gets a list of characters in the text.

Returns:: The list of characters
Return type:: XACharacterList
Example 1:: Get all characters in a text

>>> import PyXA
>>> app = PyXA.Application("Notes")
>>> note = app.notes()[0]
>>> text = PyXA.XAText(note.plaintext)
>>> print(text.characters())
<<class 'PyXA.XACharacterList'>['T', 'h', 'i', 's', ' ', 'i', 's', ' ', 't', 'h', 'e', ' ', 'f', 'i', 'r', 's', 't', ' ', 'p', 'a', 'r', 'a', 'g', 'r', 'a', 'p', 'h', '.', '\n', '\n', 'T', 'h', 'i', 's', ' ', 'i', 's', ' ', 't', 'h', 'e', ' ', 's', 'e', 'c', 'o', 'n', 'd', ' ', 'p', 'a', 'r', 'a', 'g', 'r', 'a', 'p', 'h', '.', ' ', 'N', 'e', 'a', 't', '!', ' ', 'V', 'e', 'r', 'y', ' ', 'c', 'o', 'o', 'l', '.']>

Example 2:: Get the characters of the first word in a text

>>> import PyXA
>>> app = PyXA.Application("Notes")
>>> note = app.notes()[0]
>>> text = PyXA.XAText(note.plaintext)
>>> print(text.words()[0].characters())
<<class 'PyXA.XACharacterList'>['T', 'h', 'i', 's']>

New in version 0.0.1.

property color: XAColor: The color of the first character

extract_addresses()[source]

Gets a list of addresses in the text.

Returns:: The list of addresses.
Return type:: list[XALocation]

New in version 0.3.0.

extract_dates() → list[XADatetimeBlock][source]

Gets a list of dates and durations in the text.

Returns:: The list of dates.
Return type:: list[XADatetimeBlock]

New in version 0.3.0.

extract_phone_numbers()[source]

Gets a list of phone numbers in the text.

Returns:: The list of phone numbers.
Return type:: list[XAText]

New in version 0.3.0.

extract_urls() → list[XAURL][source]

Gets a list of URLs in the text.

Returns:: The list of URLs.
Return type:: list[XAURL]

New in version 0.3.0.

property font: str: The name of the font of the first character

paragraphs(filter: dict | None = None) → XAParagraphList[source]

Gets a list of paragraphs in the text.

Parameters:: filter (dict, optional) – The properties and associated values to filter paragraphs by, defaults to None
Returns:: The list of paragraphs
Return type:: XAParagraphList
Example 1:: Get paragraphs of a text string

>>> import PyXA
>>> string = """This is the first paragraph.
>>>
>>> This is the second paragraph."""
>>> text = PyXA.XAText(string)
>>> print(text.paragraphs())
<<class 'PyXA.XAWordList'>['This is the first paragraph.', 'This is the second paragraph. Neat! Very cool.']>

Example 2:: Get paragraphs of a Note

>>> import PyXA
>>> app = PyXA.Application("Notes")
>>> note = app.notes()[0]
>>> text = PyXA.XAText(note.plaintext)
>>> print(text.paragraphs())
<<class 'PyXA.XAWordList'>['This is the first paragraph.', 'This is the second paragraph. Neat! Very cool.']>

New in version 0.0.1.

sentences() → XASentenceList[source]

Gets a list of sentences in the text.

Returns:: The list of sentencnes
Return type:: XASentenceList
Example:

>>> import PyXA
>>> app = PyXA.Application("Notes")
>>> note = app.notes()[0]
>>> text = PyXA.XAText(note.plaintext)
>>> print(text.sentences())
<<class 'PyXA.XASentenceList'>['This is the first paragraph.\n', '\n', 'This is the second paragraph. ', 'Neat! ', 'Very cool.']>

New in version 0.1.0.

property size: int: The size in points of the first character

tag_entities(unit: Literal['word', 'sentence', 'paragraph', 'document'] = 'word') → list[tuple[str, str]][source]

Tags each word of the text with either the category of entity it represents (i.e. person, place, or organization) or its part of speech.

Parameters:: unit (Literal["word", "sentence", "paragraph", "document"]) – The grammatical unit to divide the text into for tagging, defaults to “word”
Returns:: A list of tuples identifying each word of the text and its entity category or part of speech
Return type:: list[tuple[str, str]]
Example:

>>> import PyXA
>>> text = PyXA.XAText("Tim Cook is the CEO of Apple.")
>>> print(text.tag_entities())
[('Tim', 'PersonalName'), ('Cook', 'PersonalName'), ('is', 'Verb'), ('the', 'Determiner'), ('CEO', 'Noun'), ('of', 'Preposition'), ('Apple', 'OrganizationName')]

New in version 0.1.0.

tag_languages(unit: Literal['word', 'sentence', 'paragraph', 'document'] = 'paragraph') → list[tuple[str, str]][source]

Tags each paragraph of the text with its language.

Parameters:: unit (Literal["word", "sentence", "paragraph", "document"]) – The grammatical unit to divide the text into for tagging, defaults to “paragraph”
Returns:: A list of tuples identifying each paragraph of the text and its language
Return type:: list[tuple[str, str]]
Example:

>>> import PyXA
>>> text = PyXA.XAText("This is English.\nQuesto è Italiano.\nDas ist deutsch.\nこれは日本語です。")
>>> print(text.tag_languages())
[('This is English.\n', 'en'), ('Questo è Italiano.\n', 'it'), ('Das ist deutsch.\n', 'de'), ('これは日本語です。', 'ja')]

New in version 0.1.0.

tag_lemmas(unit: Literal['word', 'sentence', 'paragraph', 'document'] = 'word') → list[tuple[str, str]][source]

Tags each word of the text with its stem word.

Parameters:: unit (Literal["word", "sentence", "paragraph", "document"]) – The grammatical unit to divide the text into for tagging, defaults to “word”
Returns:: A list of tuples identifying each word of the text and its stem words
Return type:: list[tuple[str, str]]
Example 1:: Lemmatize each word in a text

>>> import PyXA
>>> text = PyXA.XAText("Here’s to the crazy ones. The misfits. The rebels.")
>>> print(text.tag_lemmas())
[('Here’s', 'here'), ('to', 'to'), ('the', 'the'), ('crazy', 'crazy'), ('ones', 'one'), ('The', 'the'), ('misfits', 'misfit'), ('The', 'the'), ('rebels', 'rebel')]

Example 2:: Combine parts of speech tagging and lemmatization

>>> import PyXA
>>> text = PyXA.XAText("The quick brown fox tries to jump over the sleeping lazy dog.")
>>> verbs = [pos[0] for pos in text.tag_parts_of_speech() if pos[1] == "Verb"]
>>> for index, verb in enumerate(verbs):
>>>     print(index, PyXA.XAText(verb).tag_lemmas())
0 [('tries', 'try')]
1 [('jump', 'jump')]
2 [('sleeping', 'sleep')]

New in version 0.1.0.

tag_parts_of_speech(unit: Literal['word', 'sentence', 'paragraph', 'document'] = 'word') → list[tuple[str, str]][source]

Tags each word of the text with its associated part of speech.

Parameters:: unit (Literal["word", "sentence", "paragraph", "document"]) – The grammatical unit to divide the text into for tagging, defaults to “word”
Returns:: A list of tuples identifying each word of the text and its part of speech
Return type:: list[tuple[str, str]]
Example 1:: Extract nouns from a text

>>> import PyXA
>>> text = PyXA.XAText("Here’s to the crazy ones. The misfits. The rebels.")
>>> nouns = [pos[0] for pos in text.tag_parts_of_speech() if pos[1] == "Noun"]
>>> print(nouns)
['ones', 'misfits', 'rebels']

New in version 0.1.0.

tag_sentiments(sentiment_scale: list[str] | None = None, unit: Literal['word', 'sentence', 'paragraph', 'document'] = 'paragraph') → list[tuple[str, str]][source]

Tags each paragraph of the text with a sentiment rating.

Parameters:

sentiment_scale (list[str]) – A list of terms establishing a range of sentiments from most negative to most postive
unit (Literal["word", "sentence", "paragraph", "document"]) – The grammatical unit to divide the text into for tagging, defaults to “paragraph”

Returns:

A list of tuples identifying each paragraph of the text and its sentiment rating

Return type:

list[tuple[str, str]]

Example 1:

Assess the sentiment of a string

>>> import PyXA
>>> text = PyXA.XAText("This sucks.\nBut this is great!")
>>> print(text.tag_sentiments())
[('This sucks.\n', 'Negative'), ('But this is great!', 'Positive')]

Example 2:: Use a custom sentiment scale

>>> import PyXA
>>> text = PyXA.XAText("This sucks.\nBut this is good!\nAnd this is great!")
>>> print(text.tag_sentiments(sentiment_scale=["Very Negative", "Negative", "Somewhat Negative", "Neutral", "Somewhat Positive", "Positive", "Very Positive"]))
[('This sucks.\n', 'Very Negative'), ('But this is good!\n', 'Neutral'), ('And this is great!', 'Very Positive')]

Example 3:: Use other tag units

>>> import PyXA
>>> text = PyXA.XAText("This sucks.\nBut this is good!\nAnd this is great!")
>>> print(1, text.tag_sentiments())
>>> print(2, text.tag_sentiments(unit="word"))
>>> print(3, text.tag_sentiments(unit="document"))
1 [('This sucks.\n', 'Negative'), ('But this is good!\n', 'Neutral'), ('And this is great!', 'Positive')]
2 [('This', 'Negative'), ('sucks', 'Negative'), ('.', 'Negative'), ('But', 'Neutral'), ('this', 'Neutral'), ('is', 'Neutral'), ('good', 'Neutral'), ('!', 'Neutral'), ('And', 'Positive'), ('this', 'Positive'), ('is', 'Positive'), ('great', 'Positive'), ('!', 'Positive')]
3 [('This sucks.\nBut this is good!\nAnd this is great!', 'Neutral')]

New in version 0.1.0.

property text: str: The plaintext contents of the rich text

words(filter: dict | None = None) → XAWordList[source]

Gets a list of words in the text.

Returns:: The list of words
Return type:: XAWordList
Example:

>>> import PyXA
>>> app = PyXA.Application("Notes")
>>> note = app.notes()[0]
>>> text = PyXA.XAText(note.plaintext)
>>> print(text.words())
<<class 'PyXA.XAWordList'>['This', 'is', 'the', 'first', 'paragraph.', 'This', 'is', 'the', 'second', 'paragraph.', 'Neat!', 'Very', 'cool.']>

New in version 0.0.1.

class PyXA.XABase.XATextDocument(properties)[source]

Bases: XAObject

A class for managing and interacting with text documents.

New in version 0.0.1.

Attributes:

`__annotations__`
`__module__`
`text`	The text of the document.

Methods:

`__init__`(properties)	Instantiates a PyXA scripting object.
`append`(text)	Appends the provided text to the end of the document.
`attachments`([filter])
`attribute_runs`([filter])
`characters`([filter])
`paragraphs`([filter])
`prepend`(text)	Inserts the provided text at the beginning of the document.
`reverse`()	Reverses the text of the document.
`sentences`([filter])
`words`([filter])

__annotations__ = {}

__init__(properties)[source]

Instantiates a PyXA scripting object.

Parameters:: properties (dict, optional) – A dictionary of properties to assign to this object.

Changed in version 0.0.3: Removed on-the-fly creation of class attributes. All objects should concretely define their properties.

New in version 0.0.1.

__module__ = 'PyXA.XABase'

append(text: str) → XATextDocument[source]

Appends the provided text to the end of the document.

Parameters:: text (str) – The text to append.
Returns:: A reference to the document object.
Return type:: XATextDocument

See also

prepend(), set_text()

New in version 0.0.1.

attachments(filter: dict | None = None) → XAAttachmentList[source]

attribute_runs(filter: dict | None = None) → XAAttributeRunList[source]

characters(filter: dict | None = None) → XACharacterList[source]

paragraphs(filter: dict | None = None) → XAParagraphList[source]

prepend(text: str) → XATextDocument[source]

Inserts the provided text at the beginning of the document.

Parameters:: text (str) – The text to insert.
Returns:: A reference to the document object.
Return type:: XATextDocument

See also

append(), set_text()

New in version 0.0.1.

reverse() → XATextDocument[source]

Reverses the text of the document.

Returns:: A reference to the document object.
Return type:: XATextDocument

New in version 0.0.4.

sentences(filter: dict | None = None) → XASentenceList[source]

property text: XAText: The text of the document.

words(filter: dict | None = None) → XAWordList[source]

class PyXA.XABase.XATextDocumentList(properties: dict, filter: dict | None = None, obj_class=None)[source]

Bases: XAList, XAClipboardCodable

A wrapper around lists of text documents that employs fast enumeration techniques.

New in version 0.1.0.

Attributes:

`__annotations__`
`__module__`

Methods:

`__init__`(properties[, filter, obj_class])	Creates an efficient wrapper object around a list of scriptable elements.
`__repr__`()	Return repr(self).
`attachments`()
`attribute_runs`()
`by_properties`(properties)
`by_text`(text)
`characters`()
`get_clipboard_representation`()	Gets a clipboard-codable representation of each document in the list.
`paragraphs`()
`properties`()
`text`()
`words`()

__annotations__ = {}

__init__(properties: dict, filter: dict | None = None, obj_class=None)[source]

Creates an efficient wrapper object around a list of scriptable elements.

Parameters:

properties (dict) – PyXA properties passed to this object for utility purposes
object_class (type, optional) – _description_, defaults to None
filter (Union[dict, None], optional) – A dictionary of properties and values to filter items by, defaults to None

Changed in version 0.0.8: The filter property is deprecated and will be removed in a future version. Use the filter() method instead.

New in version 0.0.3.

__module__ = 'PyXA.XABase'

__repr__()[source]: Return repr(self).

attachments() → XAAttachmentList[source]

attribute_runs() → XAAttributeRunList[source]

by_properties(properties: dict) → XATextDocument | None[source]

by_text(text: str) → XATextDocument | None[source]

characters() → XACharacterList[source]

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

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

When the clipboard content is set to a list of documents, each documents’s file URL and name are added to the clipboard.

Returns:: A list of each document’s file URL and name
Return type:: list[Union[str, AppKit.NSURL]]

New in version 0.0.8.

paragraphs() → XAParagraphList[source]

properties() → list[dict][source]

text() → XATextList[source]

words() → XAWordList[source]

class PyXA.XABase.XATextList(properties: dict, filter: dict | None = None, obj_class=None)[source]

Bases: XAList

A wrapper around lists of text objects that employs fast enumeration techniques.

New in version 0.0.4.

Attributes:

`__annotations__`
`__module__`

Methods:

`__init__`(properties[, filter, obj_class])	Creates an efficient wrapper object around a list of scriptable elements.
`__repr__`()	Return repr(self).
`attachments`([filter])
`attribute_runs`([filter])
`characters`([filter])
`paragraphs`([filter])
`sentences`()
`words`([filter])

__annotations__ = {}

__init__(properties: dict, filter: dict | None = None, obj_class=None)[source]

Creates an efficient wrapper object around a list of scriptable elements.

Parameters:

properties (dict) – PyXA properties passed to this object for utility purposes
object_class (type, optional) – _description_, defaults to None
filter (Union[dict, None], optional) – A dictionary of properties and values to filter items by, defaults to None

Changed in version 0.0.8: The filter property is deprecated and will be removed in a future version. Use the filter() method instead.

New in version 0.0.3.

__module__ = 'PyXA.XABase'

__repr__()[source]: Return repr(self).

attachments(filter: dict | None = None) → XAAttachmentList[source]

attribute_runs(filter: dict | None = None) → XAAttributeRunList[source]

characters(filter: dict | None = None) → XACharacterList[source]

paragraphs(filter: dict | None = None) → XAParagraphList[source]

sentences() → XASentenceList[source]

words(filter: dict | None = None) → XAWordList[source]

class PyXA.XABase.XAURL(url: str | NSURL | XAURL | XAPath)[source]

Bases: XAObject, XAClipboardCodable

A URL using any scheme recognized by the system. This can be a file URL.

New in version 0.0.5.

Attributes:

`__annotations__`
`__hash__`
`__module__`
`base_url`
`fragment`	The fragment identifier following a # symbol in the URL.
`html`	The html of the URL.
`parameters`	The query parameters of the URL.
`port`	The port that the URL points to.
`scheme`	The URI scheme of the URL.
`soup`	The bs4 object for the URL, starts as None until a bs4-related action is made
`title`	The title of the URL.
`url`	The string form of the URL

Methods:

`__eq__`(other)	Return self==value.
`__init__`(url)	Instantiates a PyXA scripting object.
`__repr__`()	Return repr(self).
`__str__`()	Return str(self).
`extract_images`()	Extracts all images from HTML of the webpage that the URL points to.
`extract_text`()	Extracts the visible text from the webpage that the URL points to.
`get_clipboard_representation`()	Gets a clipboard-codable representation of the URL.
`open`()	Opens the URL in the appropriate default application.

__annotations__ = {'soup': 'BeautifulSoup', 'url': 'str'}

__eq__(other: XAURL)[source]: Return self==value.

__hash__ = None

__init__(url: str | NSURL | XAURL | XAPath)[source]

Instantiates a PyXA scripting object.

Parameters:: properties (dict, optional) – A dictionary of properties to assign to this object.

Changed in version 0.0.3: Removed on-the-fly creation of class attributes. All objects should concretely define their properties.

New in version 0.0.1.

__module__ = 'PyXA.XABase'

__repr__()[source]: Return repr(self).

__str__()[source]: Return str(self).

property base_url: str

extract_images() → list[XAImage][source]

Extracts all images from HTML of the webpage that the URL points to.

Returns:: The list of extracted images
Return type:: list[XAImage]

New in version 0.0.8.

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

Extracts the visible text from the webpage that the URL points to.

Returns:: The list of extracted lines of text
Return type:: list[str]

New in version 0.0.8.

property fragment: str: The fragment identifier following a # symbol in the URL.

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

Gets a clipboard-codable representation of the URL.

When the clipboard content is set to a URL, the raw URL data and the string representation of the URL are added to the clipboard.

Returns:: The clipboard-codable form of the URL
Return type:: Any

New in version 0.0.8.

property html: Tag: The html of the URL.

open()[source]: Opens the URL in the appropriate default application.

New in version 0.0.5.

property parameters: str: The query parameters of the URL.

property port: int: The port that the URL points to.

property scheme: str: The URI scheme of the URL.

soup: BeautifulSoup: The bs4 object for the URL, starts as None until a bs4-related action is made

property title: str: The title of the URL.

url: str: The string form of the URL

class PyXA.XABase.XAURLList(properties: dict, filter: dict | None = None)[source]

Bases: XAList

A list of URLs. Supports bulk operations.

New in version 0.1.2.

Attributes:

`__annotations__`
`__module__`

Methods:

`__init__`(properties[, filter])	Creates an efficient wrapper object around a list of scriptable elements.
`base_url`()
`extract_images`()	Extracts the images of each URL in the list.
`extract_text`()	Extracts the visible text of each URL in the list.
`fragment`()
`html`()
`open`()	Opens each URL in the list.
`parameters`()
`port`()
`scheme`()
`title`()

__annotations__ = {}

__init__(properties: dict, filter: dict | None = None)[source]

Creates an efficient wrapper object around a list of scriptable elements.

Parameters:

properties (dict) – PyXA properties passed to this object for utility purposes
object_class (type, optional) – _description_, defaults to None
filter (Union[dict, None], optional) – A dictionary of properties and values to filter items by, defaults to None

Changed in version 0.0.8: The filter property is deprecated and will be removed in a future version. Use the filter() method instead.

New in version 0.0.3.

__module__ = 'PyXA.XABase'

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

extract_images() → list[list[XAImage]][source]: Extracts the images of each URL in the list.

New in version 0.1.2.

extract_text() → list[list[str]][source]: Extracts the visible text of each URL in the list.

New in version 0.1.2.

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

html() → list[Tag][source]

open()[source]: Opens each URL in the list.

New in version 0.1.2.

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

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

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

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

class PyXA.XABase.XAUserDomainObject(properties)[source]

Bases: XADomain

The user domain in the file system.

New in version 0.1.0.

Attributes:

`__annotations__`
`__module__`
`desktop_folder`	The user's Desktop folder
`documents_folder`	The user's Documents folder
`downloads_folder`	The user's Downloads folder
`favorites_folder`	The user's Favorites folder
`home_folder`	The user's Home folder
`movies_folder`	The user's Movies folder
`music_folder`	The user's Music folder
`pictures_folder`	The user's Pictures folder
`public_folder`	The user's Public folder
`sites_folder`	The user's Sites folder
`temporary_items_folder`	The Temporary Items folder

Methods:

__init__(properties)

Instantiates a PyXA scripting object.

__annotations__ = {}

__init__(properties)[source]

Instantiates a PyXA scripting object.

Parameters:: properties (dict, optional) – A dictionary of properties to assign to this object.

Changed in version 0.0.3: Removed on-the-fly creation of class attributes. All objects should concretely define their properties.

New in version 0.0.1.

__module__ = 'PyXA.XABase'

property desktop_folder: XAFolder: The user’s Desktop folder

New in version 0.1.0.

property documents_folder: XAFolder: The user’s Documents folder

New in version 0.1.0.

property downloads_folder: XAFolder: The user’s Downloads folder

New in version 0.1.0.

property favorites_folder: XAFolder: The user’s Favorites folder

New in version 0.1.0.

property home_folder: XAFolder: The user’s Home folder

New in version 0.1.0.

property movies_folder: XAFolder: The user’s Movies folder

New in version 0.1.0.

property music_folder: XAFolder: The user’s Music folder

New in version 0.1.0.

property pictures_folder: XAFolder: The user’s Pictures folder

New in version 0.1.0.

property public_folder: XAFolder: The user’s Public folder

New in version 0.1.0.

property sites_folder: XAFolder: The user’s Sites folder

New in version 0.1.0.

property temporary_items_folder: XAFolder: The Temporary Items folder

New in version 0.1.0.

class PyXA.XABase.XAVideo(video_reference: str | XAURL | XAPath)[source]

Bases: XAObject

A class for interacting with video files and data.

New in version 0.1.0.

Attributes:

`__annotations__`
`__module__`

Methods:

`__init__`(video_reference)	Instantiates a PyXA scripting object.
`reverse`(output_file)	Reverses the video and exports the result to the specified output file path.
`save`(file_path)	Saves the video at the specified file path.
`show_in_quicktime`()	Shows the video in QuickTime Player.

__annotations__ = {}

__init__(video_reference: str | XAURL | XAPath)[source]

Instantiates a PyXA scripting object.

Parameters:: properties (dict, optional) – A dictionary of properties to assign to this object.

Changed in version 0.0.3: Removed on-the-fly creation of class attributes. All objects should concretely define their properties.

New in version 0.0.1.

__module__ = 'PyXA.XABase'

reverse(output_file: XAPath | str)[source]

Reverses the video and exports the result to the specified output file path.

Parameters:: output_file (Union[XAPath, str]) – The file to export the reversed video to

New in version 0.1.0.

save(file_path: XAPath | str)[source]

Saves the video at the specified file path.

Parameters:: file_path (Union[XAPath, str]) – The path to save the video at

New in version 0.1.0.

show_in_quicktime()[source]

Shows the video in QuickTime Player.

This will create a momentary video data file in the current working directory to store intermediary video data.

New in version 0.1.0.

class PyXA.XABase.XAWord(properties)[source]

Bases: XAText

A class for managing and interacting with words in text documents.

New in version 0.0.1.

Attributes:

`__annotations__`
`__module__`

Methods:

__init__(properties)

Instantiates a PyXA scripting object.

__annotations__ = {'color': 'XAColor', 'font': 'str', 'size': 'int', 'text': 'str'}

__init__(properties)[source]

Instantiates a PyXA scripting object.

Parameters:: properties (dict, optional) – A dictionary of properties to assign to this object.

Changed in version 0.0.3: Removed on-the-fly creation of class attributes. All objects should concretely define their properties.

New in version 0.0.1.

__module__ = 'PyXA.XABase'

class PyXA.XABase.XAWordList(properties: dict, filter: dict | None = None)[source]

Bases: XATextList

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

New in version 0.0.5.

Attributes:

`__annotations__`
`__module__`

Methods:

__init__(properties[, filter])

Creates an efficient wrapper object around a list of scriptable elements.

__annotations__ = {}

__init__(properties: dict, filter: dict | None = None)[source]

Creates an efficient wrapper object around a list of scriptable elements.

Parameters:

properties (dict) – PyXA properties passed to this object for utility purposes
object_class (type, optional) – _description_, defaults to None
filter (Union[dict, None], optional) – A dictionary of properties and values to filter items by, defaults to None

Changed in version 0.0.8: The filter property is deprecated and will be removed in a future version. Use the filter() method instead.

New in version 0.0.3.

__module__ = 'PyXA.XABase'

PyXA.XABase.active_browser() → XAApplication[source]

Retrieves a PyXA representation of the most recently active browser application. The browser must have at least one open window. The browser must be one of the ones listed in SUPPORTED_BROWSERS.

Returns:: A PyXA application object referencing the current browser application.
Return type:: XAApplication

New in version 0.3.0.

PyXA.XABase.camelize(text: str) → str[source]

Converts a string to camel case.

Parameters:: text (str) – The string to convert
Returns:: The camelized string
Return type:: str

New in version 0.3.0.

PyXA.XABase.current_application() → XAApplication[source]

Retrieves a PyXA representation of the frontmost application.

Returns:: A PyXA application object referencing the current application.
Return type:: XAApplication

Changed in version 0.1.1: Moved into the XABase module.

New in version 0.0.1.

PyXA.XABase.running_applications(unique=True) → list[XAApplication][source]

Gets PyXA references to all currently visible (not hidden or minimized) running applications whose app bundles are stored in typical application directories. Applications are ordered by their z-index, with the frontmost application first.

Parameters:: unique (bool, optional) – Whether to return only one instance of each application, defaults to True
Returns:: A list of PyXA application objects.
Return type:: list[XAApplication]
Example 1:: Get the name of each running application

>>> import PyXA
>>> apps = PyXA.running_applications()
>>> print(apps.localized_name())
['GitHub Desktop', 'Safari', 'Code', 'Terminal', 'Notes', 'Messages', 'TV']

Changed in version 0.3.0: Added the unique parameter.

New in version 0.0.1.

PyXA.XABase.snakify(text: str) → str[source]

Converts a string to snake case.

Parameters:: text (str) – The string to convert
Returns:: The snakeized string
Return type:: str

New in version 0.3.0.

PyXA.XABase.supported_applications: list[str] = ['database events', 'finder', 'safari', 'music', 'reminders', 'notes', 'messages', 'calendar', 'textedit', 'pages', 'terminal', 'preview', 'tv', 'contacts', 'shortcuts', 'shortcuts events', 'photos', 'system preferences', 'system settings', 'keynote', 'mail', 'automator', 'console', 'font book', 'quicktime player', 'numbers', 'script editor', 'system events', 'image events', 'calculator', 'dictionary', 'maps', 'stocks', 'chromium', 'brave browser', 'brave browser dev', 'brave browser beta', 'brave browser nightly', 'microsoft edge', 'microsoft edge dev', 'microsoft edge beta', 'microsoft edge canary', 'google chrome', 'google chrome canary', 'google chrome dev', 'google chrome beta', 'opera', 'opera developer', 'opera beta', 'opera gx', 'opera neon', 'vivaldi', 'blisk', 'iridium', 'yandex', 'maxthon', 'maxthon beta', 'alfred', 'drafts', 'hammerspoon', 'rstudio', 'iterm', 'vlc', 'fantastical', 'omnioutliner', 'spotify', 'flow', 'bike', 'adobe acrobat reader', 'cardhop', 'amphetamine', 'iina', 'omniweb', 'path finder', 'arc']: A list of names of supported scriptable applications

PyXA.XABase.unOSType(i: int)[source]