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

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()

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'
class PyXA.XABase.XADialog(text: str = '', title: str | None = None, buttons: None | list[str | int] = None, hidden_answer: bool = False, default_button: str | int | None = None, cancel_button: str | int | None = None, icon: Literal['stop', 'note', 'caution'] | None = None, default_answer: str | int | None = None)[source]

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'}
__init__(text: str = '', title: str | None = None, buttons: None | list[str | int] = None, hidden_answer: bool = False, default_button: str | int | None = None, cancel_button: str | int | None = None, icon: Literal['stop', 'note', 'caution'] | None = None, default_answer: str | int | 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'
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)