Safari Module Reference

New in version 0.0.1.

Control Safari using JXA-like syntax.

Classes:

`XASafariApplication`(properties)	A class for interacting with Safari.app.
`XASafariDocument`(properties)	A class for interacting with Safari documents.
`XASafariDocumentList`(properties[, filter])	A wrapper around lists of Safari documents that employs fast enumeration techniques.
`XASafariGeneric`(properties)	A generic class containing methods relevant to Safari tabs and documents.
`XASafariTab`(properties)	A class for interacting with Safari tabs.
`XASafariTabList`(properties[, filter])	A wrapper around lists of tabs that employs fast enumeration techniques.
`XASafariWindow`(properties)	A window of Safari.app.

class PyXA.apps.Safari.XASafariApplication(properties)[source]

Bases: XASBApplication, XASBPrintable, XAObject, XACanOpenPath

A class for interacting with Safari.app.

See also

XASafariDocument, XASafariTab, XABaseScriptable.XASBApplication, XABaseScriptable.XASBSaveable, XABaseScriptable.XASBPrintable

New in version 0.0.1.

Classes:

ObjectType(value)

Object types that can be created using make().

Methods:

`add_to_reading_list`(item)	Adds a URL to the reading list.
`do_javascript`(script[, tab])	Runs JavaScript in the specified tab.
`documents`([filter])	Returns a list of documents matching the given filter.
`email`(item)	Opens a new email draft with the content of a tab or document.
`make`(specifier, properties[, data])	Creates a new element of the given specifier class without adding it to any list.
`new_tab`(url)	Activates Safari to a new tab at the specified URL or path.
`open`([url])	Opens a URL in new tab.
`save`()
`search`(term)	Activates Safari and searches the specified string in a new tab of the frontmost Safari window.
`search_in_tab`(tab, term)	Searches the given search string in the specified tab.
`show_bookmarks`()	Activates Safari and opens Safari's bookmarks page.

Attributes:

`current_document`	The currently displayed document in the active tab.
`current_tab`	The currently active tab.
`frontmost`	Whether Safari is the active application.
`name`	The name of the application.
`version`	The version of Safari.app.

class ObjectType(value)[source]

Bases: Enum

Object types that can be created using make().

Attributes:

`DOCUMENT`
`TAB`

DOCUMENT = 'document'

TAB = 'tab'

add_to_reading_list(item: str | XAURL | XASafariTab | XASafariDocument) → XASafariApplication[source]

Adds a URL to the reading list.

Parameters:: item (Union[str, XASafariTab, XASafariDocument]) – A URL string or a Safari tab or document containing the URL to add to the reading list.
Returns:: A reference to the Safari application object.
Return type:: XASafariTab
Example:

>>> import PyXA
>>> app = PyXA.Application("Safari")
>>> window = app.front_window
>>> doc = app.current_document
>>> tab = window.current_tab
>>> app.add_to_reading_list(doc)
>>> app.add_to_reading_list(tab)

New in version 0.0.1.

property current_document: XASafariDocument: The currently displayed document in the active tab.

property current_tab: XASafariTab: The currently active tab.

do_javascript(script: str, tab: XASafariTab | None = None) → Any[source]

Runs JavaScript in the specified tab. If no tab is specified, the script is run in the current tab of the frontmost Safari window.

Parameters:

script (str) – The script to run.
tab (XASafariTab) – The tab to execute the JavaScript script in, defaults to None

Returns:

The value returned from the script after it completes execution.

Return type:

Any

Example:

>>> import PyXA
>>> app = PyXA.Application("Safari")
>>> tab = app.front_window.current_tab
>>> script = "(function example() { return 1 + 1 })()"
>>> print(app.do_javascript(script, tab))
2.0

New in version 0.0.1.

documents(filter: dict | None = None) → XASafariDocumentList[source]: Returns a list of documents matching the given filter.

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

New in version 0.0.1.

email(item: XASafariDocument | XASafariTab)[source]

Opens a new email draft with the content of a tab or document.

Parameters:: item (Union[XASafariDocument, XASafariTab]) – The object to email

New in version 0.0.4.

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

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

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

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

Parameters:

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

Returns:

A PyXA wrapped form of the object

Return type:

XABase.XAObject

Example 1:

Make a new tab in Safari’s front window

>>> import PyXA
>>> app = PyXA.Application("Safari")
>>> new_tab = app.make("tab", {"URL": "http://google.com"})
>>> app.front_window.tabs().push(new_tab)

Example 2:: Open a page in a new window by making a new document

>>> import PyXA
>>> app = PyXA.Application("Safari")
>>> new_doc = app.make("document", {"URL": "http://google.com"})
>>> app.documents().push(new_doc)

New in version 0.0.4.

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

new_tab(url: str | XAURL | XAPath) → XASafariTab[source]

Activates Safari to a new tab at the specified URL or path.

Parameters:: url (Union[str, XABase.XAURL, XABase.XAPath]) – The URL or path to open in a new tab
Returns:: A reference to the newly opened tab
Return type:: XASafariTab

New in version 0.1.0.

open(url: str | XAURL | XAPath = 'https://google.com') → XASafariTab[source]

Opens a URL in new tab.

Parameters:: url (Union[str, XABase.XAURL, XABase.XAPath], optional) – The URL or path to open, defaults to “http://google.com”
Returns:: A reference to the newly created tab object
Return type:: XASafariTab
Example 1:: Open local and external URLs

>>> import PyXA
>>> app = PyXA.Application("Safari")
>>> app.open("https://www.google.com")
>>> app.open("google.com")
>>> app.open("/Users/exampleuser/Documents/WebPage.html")

New in version 0.0.1.

save()[source]

search(term: str) → XASafariApplication[source]

Activates Safari and searches the specified string in a new tab of the frontmost Safari window. Uses the default search engine.

Parameters:: term (str) – The string to search
Returns:: A reference to the newly opened Search tab
Return type:: XASafariTab
Example:

>>> import PyXA
>>> app = PyXA.Application("Safari")
>>> app.search("What is PyXA?")

See also

search_in_tab()

New in version 0.0.1.

search_in_tab(tab: XASafariTab, term: str) → XASafariApplication[source]

Searches the given search string in the specified tab. Uses the default search engine.

Parameters:

tab (XASafariTab) – The tab to conduct the web search in.
term (str) – The string to search.

Returns:

A reference to the tab object

Return type:

XASafariTab

Example:

>>> import PyXA
>>> app = PyXA.Application("Safari")
>>> tab = app.front_window.current_tab
>>> app.search_in_tab(tab, "What is PyXA?")

See also

search()

New in version 0.0.1.

show_bookmarks() → XASafariApplication[source]

Activates Safari and opens Safari’s bookmarks page.

Returns:: A reference to the newly opened Bookmarks tab
Return type:: XASafariTab

New in version 0.0.1.

property version: str: The version of Safari.app.

class PyXA.apps.Safari.XASafariDocument(properties)[source]

Bases: XASafariGeneric, XAClipboardCodable, XASBPrintable

A class for interacting with Safari documents.

See also

XASafariGeneric, XABaseScriptable.XASBPrintable, XABaseScriptable.XASBSaveable

New in version 0.0.1.

Attributes:

`file`	The location of the document on the disk, if there is one.
`modified`	Whether the document has been modified since its last save.
`name`	The title of the document.
`source`	The HTML source of the web page currently loaded in the document.
`text`	The text of the web page currently loaded in the document.
`url`	The current URL of the document.

Methods:

`get_clipboard_representation`()	Gets a clipboard-codable representation of the document.
`print`([properties, show_dialog])	Prints or opens the print dialog for the document.

property file: str: The location of the document on the disk, if there is one.

get_clipboard_representation() → NSURL[source]

Gets a clipboard-codable representation of the document.

When the clipboard content is set to a Safari document, the document’s URL is added to the clipboard.

Returns:: The document’s URL
Return type:: AppKit.NSURL

New in version 0.0.8.

property modified: bool: Whether the document has been modified since its last save.

property name: str: The title of the document.

print(properties: dict | None = None, show_dialog: bool = True)[source]

Prints or opens the print dialog for the document.

Parameters:

properties (dict, optional) – The print properties to pre-set for the print, defaults to None
show_dialog (bool, optional) – Whether to display the print dialog, defaults to True

New in version 0.0.5.

property source: str: The HTML source of the web page currently loaded in the document.

property text: XAText: The text of the web page currently loaded in the document.

property url: XAURL: The current URL of the document.

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

Bases: XAList, XAClipboardCodable

A wrapper around lists of Safari documents that employs fast enumeration techniques.

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

New in version 0.0.4.

Methods:

`add_to_reading_list`()	Adds the URL of all documents in the list to the reading list.
`by_file`(file)
`by_modified`(modified)
`by_name`(name)
`by_source`(source)
`by_text`(text)
`by_url`(url)
`close`()	Closes each tab in the list.
`do_javascript`(script)	Runs a given JavaScript script in each document in the list.
`email`()	Opens a new email draft with embedded links to the URL of each document in the list.
`file`()
`get_clipboard_representation`()	Gets a clipboard-codable representation of each document in the list.
`modified`()
`name`()
`reload`()	Reloads all documents in the list.
`search`(term)	Searches for the given term in each document in the list, using the default search engine.
`source`()
`text`()
`url`()

add_to_reading_list() → XASafariDocumentList[source]

Adds the URL of all documents in the list to the reading list.

Returns:: A reference to the document list object.
Return type:: XASafariDocumentList

New in version 0.0.5.

by_file(file: str) → XASafariDocument | None[source]

by_modified(modified: bool) → XASafariDocument | None[source]

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

by_source(source: str) → XASafariDocument | None[source]

by_text(text: str | XAText) → XASafariDocument | None[source]

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

close()[source]: Closes each tab in the list.

New in version 0.0.5.

do_javascript(script: str) → XASafariDocumentList[source]

Runs a given JavaScript script in each document in the list.

Returns:: A reference to the document list object.
Return type:: XASafariDocumentList

New in version 0.0.5.

email() → XASafariDocumentList[source]

Opens a new email draft with embedded links to the URL of each document in the list.

Returns:: A reference to the document list object.
Return type:: XASafariDocumentList

New in version 0.0.5.

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

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

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

When the clipboard content is set to a list of Safari documents, each document’s URL is added to the clipboard.

Returns:: A list of document URLs
Return type:: list[AppKit.NSURL]

New in version 0.0.8.

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

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

reload() → XASafariDocumentList[source]

Reloads all documents in the list.

Returns:: A reference to the document list object.
Return type:: XASafariDocumentList

New in version 0.0.4.

search(term: str) → XASafariDocumentList[source]

Searches for the given term in each document in the list, using the default search engine.

Returns:: A reference to the document list object.
Return type:: XASafariDocumentList

New in version 0.0.5.

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

text() → list[XAText][source]

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

class PyXA.apps.Safari.XASafariGeneric(properties)[source]

Bases: XACloseable, XAObject

A generic class containing methods relevant to Safari tabs and documents.

See also

XASafariDocument, XASafariTab

New in version 0.0.1.

Methods:

`add_to_reading_list`()	Adds the URL of a tab or document to the reading list.
`do_javascript`(script)	Runs JavaScript in a tab or document.
`email`()	Opens a new email draft with the content of a tab or document.
`reload`()	Reloads the tab or document.
`search`(term)	Searches for the specified term in the current tab or document.

add_to_reading_list() → XASafariGeneric[source]

Adds the URL of a tab or document to the reading list.

Returns:: A reference to the object that called this method.
Return type:: XASafariGeneric

New in version 0.0.1.

do_javascript(script: str) → Any[source]

Runs JavaScript in a tab or document.

Returns:: The value returned from the script after it completes execution
Return type:: Any

New in version 0.0.1.

email() → XASafariGeneric[source]

Opens a new email draft with the content of a tab or document.

Parameters:: item (Union[XASafariDocument, XASafariTab]) – The object to email
Returns:: A reference to the object that called this method.
Return type:: XASafariGeneric

New in version 0.0.4.

reload() → XASafariGeneric[source]

Reloads the tab or document.

Returns:: A reference to the object that called this method.
Return type:: XASafariGeneric

New in version 0.0.4.

search(term: str) → XASafariGeneric[source]

Searches for the specified term in the current tab or document.

Parameters:: term (str) – The term to search
Returns:: A reference to the object that called this method
Return type:: XASafariGeneric

New in version 0.0.1.

class PyXA.apps.Safari.XASafariTab(properties)[source]

Bases: XASafariGeneric, XAClipboardCodable

A class for interacting with Safari tabs.

See also

XASafariGeneric

New in version 0.0.1.

Methods:

`duplicate_to`(window)	Duplicates the tab in the specified window.
`get_clipboard_representation`()	Gets a clipboard-codable representation of the tab.
`move_to`(window)	Moves the tab to the specified window.

Attributes:

`index`	The index of the tab, ordered left to right.
`name`	The title of the tab.
`source`	The HTML source of the web page currently loaded in the tab.
`text`	The text of the web page currently loaded in the tab.
`url`	The current URL of the tab.
`visible`	Whether the tab is currently visible.

duplicate_to(window: XASafariWindow) → XASafariTab[source]

Duplicates the tab in the specified window. The tab will then exist in two locations.

Parameters:: window (XASafariWindow) – The window to duplicate the tab in.
Returns:: A reference to the tab object.
Return type:: XASafariTab
Example:

>>> import PyXA
>>> app = PyXA.Application("Safari")
>>> tab = app.front_window.current_tab
>>> window2 = app.window(1)
>>> tab.duplicate_to(window2)

See also

move_to()

New in version 0.0.1.

get_clipboard_representation() → NSURL[source]

Gets a clipboard-codable representation of the tab.

When the clipboard content is set to a Safari tab, the tab’s URL is added to the clipboard.

Returns:: The tabs’s URL
Return type:: AppKit.NSURL

New in version 0.0.8.

property index: int: The index of the tab, ordered left to right.

move_to(window: XASafariWindow) → XASafariTab[source]

Moves the tab to the specified window. After, the tab will exist in only one location.

Parameters:: window (XASafariWindow) – The window to move the tab to.
Returns:: A reference to the tab object.
Return type:: XASafariTab
Example:

>>> import PyXA
>>> app = PyXA.Application("Safari")
>>> tab = app.front_window.current_tab
>>> window2 = app.window(1)
>>> tab.move_to(window2)

See also

duplicate_to()

New in version 0.0.1.

property name: str: The title of the tab.

property source: str: The HTML source of the web page currently loaded in the tab.

property text: XAText: The text of the web page currently loaded in the tab.

property url: XAURL: The current URL of the tab.

property visible: bool: Whether the tab is currently visible.

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

Bases: XAList, XAClipboardCodable

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

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

New in version 0.0.4.

Methods:

`add_to_reading_list`()	Adds the URL of all tabs in the list to the reading list.
`by_index`(index)
`by_name`(name)
`by_source`(source)
`by_text`(text)
`by_url`(url)
`by_visible`(visible)
`close`()	Closes each tab in the list.
`do_javascript`(script)	Runs a given JavaScript script in each tab in the list.
`duplicate_to`(window)	Duplicate all tabs in the list in the specified window.
`email`()	Opens a new email draft with embedded links to the URL of each tab in the list.
`get_clipboard_representation`()	Gets a clipboard-codable representation of each tab in the list.
`index`()	Returns the index of the first occurrence of the element in the list, or -1 if no such element exists in the list.
`move_to`(window)	Moves all tabs in the list to the specified window.
`name`()
`reload`()	Reloads all tabs in the list.
`search`(term)	Searches for the given term in each tab in the list, using the default search engine.
`source`()	Gets the source HTML of each tab in the list.
`text`()	Gets the visible text of each tab in the list.
`url`()
`visible`()

add_to_reading_list() → XASafariTabList[source]

Adds the URL of all tabs in the list to the reading list.

Returns:: A reference to the tab list object.
Return type:: XASafariTabList

New in version 0.0.5.

by_index(index: int) → XASafariTab | None[source]

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

by_source(source: str) → XASafariTab | None[source]

by_text(text: str | XAText) → XASafariTab | None[source]

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

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

close()[source]: Closes each tab in the list.

New in version 0.0.5.

do_javascript(script: str) → XASafariTabList[source]

Runs a given JavaScript script in each tab in the list.

Returns:: A reference to the tab list object.
Return type:: XASafariTabList

New in version 0.0.5.

duplicate_to(window: XASafariWindow) → XASafariTabList[source]

Duplicate all tabs in the list in the specified window.

Parameters:: window (XASafariWindow) – The window to duplicate tabs in
Returns:: The tab list object
Return type:: XASafariTabList

See also

move_to()

New in version 0.0.5.

email() → XASafariTabList[source]

Opens a new email draft with embedded links to the URL of each tab in the list.

Returns:: A reference to the tab list object.
Return type:: XASafariTabList

New in version 0.0.5.

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

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

When the clipboard content is set to a list of Safari tabs, each tabs’s URL is added to the clipboard. Pasting the copied list into an app such as Numbers will place each URL in a separate cell of a column.

Returns:: A list of tab URLs
Return type:: list[AppKit.NSURL]

New in version 0.0.8.

index() → list[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.

move_to(window: XASafariWindow) → XASafariTabList[source]

Moves all tabs in the list to the specified window.

Parameters:: window (XASafariWindow) – The window to move tabs to
Returns:: The tab list object
Return type:: XASafariTabList

See also

duplicate_to()

New in version 0.0.5.

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

reload() → XASafariTabList[source]

Reloads all tabs in the list.

Returns:: A reference to the tab list object.
Return type:: XASafariTabList

New in version 0.0.4.

search(term: str) → XASafariTabList[source]

Searches for the given term in each tab in the list, using the default search engine.

Returns:: A reference to the tab list object.
Return type:: XASafariTabList

New in version 0.0.5.

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

Gets the source HTML of each tab in the list.

This will activate Safari, individually focus each tab, refocus the original tab, then return a list of all tabs’ source HTML.

Returns:: A list of source HTML
Return type:: list[str]

New in version 0.0.4.

text() → list[XAText][source]

Gets the visible text of each tab in the list.

This will activate Safari, individually focus each tab, refocus the original tab, then return a list of all tabs’ visible text.

Returns:: A list of visible text
Return type:: list[XABase.XAText]

New in version 0.0.4.

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

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

class PyXA.apps.Safari.XASafariWindow(properties)[source]

Bases: XASBWindow, XASBPrintable, XAObject

A window of Safari.app.

New in version 0.0.1.

Attributes:

`current_tab`	The currently selected tab.
`document`	The document currently displayed in the window.

Methods:

tabs([filter])

Returns a list of tabs matching the given filter.

property current_tab: XASafariTab: The currently selected tab.

property document: XASafariDocument: The document currently displayed in the window.

tabs(filter: dict | None = None) → XASafariTabList[source]: Returns a list of tabs matching the given filter.

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

New in version 0.0.1.