System Preferences Module Reference

New in version 0.0.2.

Control the macOS System Preferences application using JXA-like syntax.

Classes:

`XAPreferenceAnchor`(properties)	A class for managing and interacting with anchors in System Preferences.
`XAPreferenceAnchorList`(properties[, filter])	A wrapper around lists of preference anchors that employs fast enumeration techniques.
`XAPreferencePane`(properties)	A class for managing and interacting with preference panes in System Preferences.
`XAPreferencePaneList`(properties[, filter])	A wrapper around lists of preference panes that employs fast enumeration techniques.
`XASystemPreferencesApplication`(properties)	A class for interacting with System Preferences.app.

class PyXA.apps.SystemPreferences.XAPreferenceAnchor(properties)[source]

Bases: XAObject

A class for managing and interacting with anchors in System Preferences.

New in version 0.0.2.

Attributes:

name

The name of the anchor.

Methods:

reveal()

Reveals the anchor in the System Preferences window.

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

reveal() → XAPreferenceAnchor[source]

Reveals the anchor in the System Preferences window.

Returns:: A reference to the anchor object.
Return type:: XAPreferenceAnchor
Example 1:: Reveal the Siri anchor in the Accessibility pane

>>> import PyXA
>>> app = PyXA.Application("System Preferences")
>>> pane = app.panes().by_name("Accessibility")
>>> anchor = pane.anchors().by_name("Siri")
>>> anchor.reveal()

New in version 0.0.4.

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

Bases: XAList

A wrapper around lists of preference anchors that employs fast enumeration techniques.

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

New in version 0.0.4.

Methods:

`by_name`(name)
`name`()

by_name(name: str) → XAPreferenceAnchor[source]

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

class PyXA.apps.SystemPreferences.XAPreferencePane(properties)[source]

Bases: XAObject

A class for managing and interacting with preference panes in System Preferences.

See also

XAPreferenceAnchor

New in version 0.0.2.

Methods:

`anchors`([filter])	Returns a list of anchors, as PyXA objects, matching the given filter.
`authorize`()	Prompts for authorization for the preference pane.
`reveal`()	Reveals the preference pane in the System Preferences window.

Attributes:

`id`	A unique identifier for the preference pane independent of locale.
`localized_name`	The locale-dependant name of the preference pane.
`name`	The name of the preference pane as it appears in the title bar.

anchors(filter: dict | None = None) → XAPreferenceAnchorList[source]

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

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

>>> import PyXA
>>> app = PyXA.Application("System Preferences")
>>> pane = app.panes()[0]
>>> print(pane.anchors())
<<class 'PyXA.apps.SystemPreferences.XAPreferenceAnchorList'>['Accessibility_Shortcut', 'Seeing_Cursor', ...]>

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

New in version 0.0.2.

authorize() → XAPreferencePane[source]

Prompts for authorization for the preference pane.

Returns:: A reference to the pane object.
Return type:: XAPreferencePane
Example 1:: Prompt for authorization for the Date & Time pane

>>> import PyXA
>>> from time import sleep
>>> app = PyXA.Application("System Preferences")
>>> app.activate()
>>> pane = app.panes().by_name("Date & Time")
>>> pane.reveal()
>>> sleep(0.5) # Wait for animation to finish
>>> pane.authorize()

New in version 0.0.2.

property id: str: A unique identifier for the preference pane independent of locale.

property localized_name: str: The locale-dependant name of the preference pane.

property name: str: The name of the preference pane as it appears in the title bar.

reveal() → XAPreferencePane[source]

Reveals the preference pane in the System Preferences window.

Returns:: A reference to the pane object.
Return type:: XAPreferencePane
Example 1:: Reveal the Displays preference pane

>>> import PyXA
>>> app = PyXA.Application("System Preferences")
>>> app.activate()
>>> app.panes().by_name("Displays").reveal()

New in version 0.0.4.

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

Bases: XAList

A wrapper around lists of preference panes that employs fast enumeration techniques.

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

Example 1:: List the name of each preference pane

>>> import PyXA
>>> app = PyXA.Application("System Preferences")
>>> print(app.panes().name())
['Accessibility', 'Apple ID', 'Battery', 'Bluetooth', ...]

Example 2:: Get a preference pane by name (two ways)

>>> import PyXA
>>> app = PyXA.Application("System Preferences")
>>> pane1 = app.panes().by_name("Battery")
>>> pane2 = app.panes({"name": "Battery"})[0]
>>> print(pane1 == pane2)
True

New in version 0.0.4.

Methods:

`by_id`(id)
`by_localized_name`(localized_name)
`by_name`(name)
`id`()
`localized_name`()
`name`()

by_id(id: str) → XAPreferencePane[source]

by_localized_name(localized_name: str) → XAPreferencePane[source]

by_name(name: str) → XAPreferencePane[source]

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

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

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

class PyXA.apps.SystemPreferences.XASystemPreferencesApplication(properties)[source]

Bases: XASBApplication

A class for interacting with System Preferences.app.

New in version 0.0.2.

Attributes:

`current_pane`	The currently selected preference pane.
`frontmost`	Whether System Preferences is the active application.
`name`	The name of the application.
`preferences_window`	The main preferences window.
`show_all`	Whether the system preferences is in show all view.
`version`	The version of System Preferences.app.

Methods:

panes([filter])

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

property current_pane: XAPreferencePane: The currently selected preference pane.

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

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

panes(filter: dict | None = None) → XAPreferencePaneList[source]

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

Parameters:: filter (Union[dict, None]) – A dictionary specifying property-value pairs that all returned preference panes will have, or None
Returns:: The list of preference panes
Return type:: list[XAPreferencePane]
Example 1:: List all preference panes

>>> import PyXA
>>> app = PyXA.Application("System Preferences")
>>> print(app.panes())
<<class 'PyXA.apps.SystemPreferences.XAPreferencePaneList'>['Accessibility', 'Apple ID', 'Battery', ...]>

Example 2:: List preference panes after applying a filter

>>> import PyXA
>>> app = PyXA.Application("System Preferences")
>>> print(app.panes({"name": "Battery"}))
<<class 'PyXA.apps.SystemPreferences.XAPreferencePaneList'>['Battery']>

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

New in version 0.0.2.

property preferences_window: XASBWindow: The main preferences window.

property show_all: bool: Whether the system preferences is in show all view.

property version: str: The version of System Preferences.app.