Messages Module Reference
New in version 0.0.1.
Control the macOS Messages application using JXA-like syntax.
Classes:
|
A class for managing and interacting with accounts in Messages.app |
|
A wrapper around a list of accounts that employs fast enumeration techniques. |
|
A class for managing and interacting with Messages.app |
|
A class for managing and interacting with chats in Messages.app |
|
A wrapper around a list of chats that employs fast enumeration techniques. |
|
A class for managing and interacting with documents in Messages.app. |
|
A wrapper around a list of documents that employs fast enumeration techniques. |
|
A class for managing and interacting with file transfers in Messages.app |
|
A wrapper around a list of file transfers that employs fast enumeration techniques. |
|
A class for managing and interacting with chat participants in Messages.app |
|
A wrapper around a list of participants that employs fast enumeration techniques. |
|
A class for managing and interacting with Messages windows. |
- class PyXA.apps.Messages.XAMessagesAccount(properties)[source]
Bases:
XAObject
,XAClipboardCodable
A class for managing and interacting with accounts in Messages.app
New in version 0.0.1.
Methods:
chats
([filter])Returns a list of chats, as PyXA objects, matching the given filter.
Gets a clipboard-codable representation of the account.
participants
([filter])Returns a list of participants, as PyXA objects, matching the given filter.
Attributes:
The connection status for the account.
Whether the account is currently enabled.
The unique identifier for the account.
The name of the account as defined in the Account Preferences description field.
The type of service for the account.
- chats(filter: dict | None = None) XAMessagesChatList [source]
Returns a list of chats, as PyXA objects, matching the given filter.
New in version 0.0.4.
- property connection_status: ConnectionStatus
The connection status for the account.
- property enabled: bool
Whether the account is currently enabled.
- get_clipboard_representation() str [source]
Gets a clipboard-codable representation of the account.
When the clipboard content is set to an account, the name of the account is added to the clipboard.
- Returns:
The name of the account
- Return type:
str
New in version 0.0.8.
- property id: str
The unique identifier for the account.
- property object_description: str
The name of the account as defined in the Account Preferences description field.
- participants(filter: dict | None = None) XAMessagesParticipantList [source]
Returns a list of participants, as PyXA objects, matching the given filter.
New in version 0.0.4.
- property service_type: ServiceType
The type of service for the account.
- class PyXA.apps.Messages.XAMessagesAccountList(properties: dict, filter: dict | None = None)[source]
Bases:
XAList
,XAClipboardCodable
A wrapper around a list of accounts that employs fast enumeration techniques.
All properties of accounts can be called as methods on the wrapped list, returning a list containing each account’s value for the property.
New in version 0.0.4.
Methods:
by_connection_status
(connection_status)by_enabled
(enabled)by_id
(id)by_object_description
(object_description)by_service_type
(service_type)enabled
()Gets a clipboard-codable representation of each account in the list.
id
()- by_connection_status(connection_status: ConnectionStatus) XAMessagesAccount | None [source]
- by_enabled(enabled: bool) XAMessagesAccount | None [source]
- by_id(id: str) XAMessagesAccount | None [source]
- by_object_description(object_description: str) XAMessagesAccount | None [source]
- by_service_type(service_type: ServiceType) XAMessagesAccount | None [source]
- connection_status() list[ConnectionStatus] [source]
- get_clipboard_representation() list[str] [source]
Gets a clipboard-codable representation of each account in the list.
When the clipboard content is set to a list of accounts, each account’s object description is added to the clipboard.
- Returns:
The list of account descriptions
- Return type:
list[str]
New in version 0.0.8.
- service_type() list[ServiceType] [source]
- class PyXA.apps.Messages.XAMessagesApplication(properties)[source]
Bases:
XASBApplication
A class for managing and interacting with Messages.app
New in version 0.0.1.
Classes:
ConnectionStatus
(value)Options for the connection status of Messages.app to message transfer servers.
MessageDirection
(value)Options for the direction of a message.
ServiceType
(value)Options for services types supported by Messages.app.
TransferStatus
(value)Options for the transfer stage/status of a message.
Methods:
accounts
([filter])Returns a list of accounts, as PyXA objects, matching the given filter.
chats
([filter])Returns a list of chats, as PyXA objects, matching the given filter.
documents
([filter])Returns a list of documents, as PyXA objects, matching the given filter.
file_transfers
([filter])Returns a list of file transfers, as PyXA objects, matching the given filter.
participants
([filter])Returns a list of participants, as PyXA objects, matching the given filter.
print
(object[, show_dialog])send
(message, chat)Sends a message to the specified chat.
Attributes:
Whether Messages is the active application.
The name of the application.
The version of Messages.app.
- class ConnectionStatus(value)[source]
Bases:
Enum
Options for the connection status of Messages.app to message transfer servers.
Attributes:
- CONNECTED = 1668247150
- CONNECTING = 1668247143
- DISCONNECTED = 1684238190
- DISCONNECTING = 1684237927
- class MessageDirection(value)[source]
Bases:
Enum
Options for the direction of a message.
Attributes:
- INCOMING = 1179937123
- OUTGOING = 1179938663
- class ServiceType(value)[source]
Bases:
Enum
Options for services types supported by Messages.app.
Attributes:
- IMESSAGE = 1936289139
- SMS = 1936944499
- class TransferStatus(value)[source]
Bases:
Enum
Options for the transfer stage/status of a message.
Attributes:
- FAILED = 1179939685
- FINALIZING = 1179939706
- FINISHED = 1179939686
- PREPARING = 1179939696
- TRANSFERRING = 1179939687
- WAITING = 1179939703
- accounts(filter: dict | None = None) XAMessagesAccountList [source]
Returns a list of accounts, as PyXA objects, matching the given filter.
- Example 1:
Print a list of all accounts
>>> import PyXA >>> messages = PyXA.Application("Messages") >>> print(messages.accounts()) <<class 'PyXA.apps.Messages.XAMessagesAccountList'>[<ServiceType.IMESSAGE: 1936289139>, <ServiceType.SMS: 1936289139>, <ServiceType.IMESSAGE: 1936289139>]>
- Example 2:
Get an account by its ID
>>> import PyXA >>> messages = PyXA.Application("Messages") >>> print(messages.accounts().by_id("BEC519EA-DD88-5574-BDB9-C48486D3111B")) <PyXA.apps.Messages.XAMessagesAccount object at 0x126de2340>
New in version 0.0.4.
- chats(filter: dict | None = None) XAMessagesChatList [source]
Returns a list of chats, as PyXA objects, matching the given filter.
- Example 1:
List all chats
>>> import PyXA >>> app = PyXA.Application("Messages") >>> print(app.chats()) <<class 'PyXA.apps.Messages.XAMessagesChatList'>['iMessage;-;+11234567891', 'SMS;-;+12234567891', ...]
- Example 2:
List the names of all named chats
>>> import PyXA >>> app = PyXA.Application("Messages") >>> print(app.chats().name()) ['PyXA Group', 'Dev Chat']
- Example 3:
List the information, including participants, of every chat
>>> import PyXA >>> app = PyXA.Application("Messages") >>> chats = app.chats() >>> for chat in chats: >>> print("\n") >>> print("Name:", chat.name) >>> print("ID:", chat.id) >>> print("Account:", chat.account) >>> print("Participants:", chat.participants()) Name: None ID: iMessage;-;+11234567891 Account: <PyXA.apps.Messages.XAMessagesAccount object at 0x10871e100> Participants: <<class 'PyXA.apps.Messages.XAMessagesParticipantList'>['+1 (123) 456-7891']> ...
New in version 0.0.4.
- documents(filter: dict | None = None) XAMessagesDocumentList [source]
Returns a list of documents, as PyXA objects, matching the given filter.
New in version 0.0.4.
- file_transfers(filter: dict | None = None) XAMessagesFileTransferList [source]
Returns a list of file transfers, as PyXA objects, matching the given filter.
- Example 1:
List all file transfers
>>> import PyXA >>> messages = PyXA.Application("Messages") >>> print(messages.file_transfers()) <<class 'PyXA.apps.Messages.XAMessagesFileTransferList'>['at_0_8BEC6B47-3B43-4D14-87C1-221C2BDED01C', 'at_0_9C0DC423-F6AB-4A98-8532-1C4D250160CD', ...]>
- Example 2:
Get a file transfer by filename
>>> import PyXA >>> messages = PyXA.Application("Messages") >>> print(messages.file_transfers().by_name("Example1.png") <<class 'PyXA.apps.Messages.XAMessagesFileTransfer'>Example1.png>
- Example 3:
List the file paths of file transfers
>>> import PyXA >>> messages = PyXA.Application("Messages") >>> print(messages.file_transfers().file_path()) [file:///Users/exampleuser/Library/Messages/Attachments/de/14/at_0_8BEC6B47-3B43-4D14-87C1-221C2BDED01C/Example1.png, file:///Users/exampleuser/Library/Messages/Attachments/c4/04/at_0_9C0DC423-F6AB-4A98-8532-1C4D250160CD/Example2.jpg, ...]
- Example 4:
Get the first PNG file transfer
>>> import PyXA >>> messages = PyXA.Application("Messages") >>> print(messages.file_transfers().containing("name", "png")) <<class 'PyXA.apps.Messages.XAMessagesFileTransfer'>Example1.png>
New in version 0.0.4.
- property frontmost: bool
Whether Messages is the active application.
New in version 0.0.1.
- property name: str
The name of the application.
New in version 0.0.1.
- participants(filter: dict | None = None) XAMessagesParticipantList [source]
Returns a list of participants, as PyXA objects, matching the given filter.
- Example 1:
List all participants
>>> import PyXA >>> messages = PyXA.Application("Messages") >>> print(messages.participants()) <<class 'PyXA.apps.Messages.XAMessagesParticipantList'>['+1 (888) 888-8888', 'Example Person', 'Another Person', ...]>
- Example 2:
Get a participant by full name
>>> import PyXA >>> messages = PyXA.Application("Messages") >>> print(messages.participants().by_full_name("Example Person")) <<class 'PyXA.apps.Messages.XAMessagesParticipant'>Example Person>
New in version 0.0.4.
- send(message: str, chat: XAMessagesChat)[source]
Sends a message to the specified chat.
- Parameters:
message (str) – The message to send
chat (XAMessagesChat) – The chat to send the message to
- Example 1:
>>> import PyXA >>> messages = PyXA.Application("Messages") >>> friend = messages.participants().by_full_name("Example Person") >>> chat = messages.chats().by_participants([friend]) >>> messages.send("Testing 1 2 3", chat)
New in version 0.0.4.
- property version: str
The version of Messages.app.
New in version 0.0.1.
- class PyXA.apps.Messages.XAMessagesChat(properties)[source]
Bases:
XAObject
,XAClipboardCodable
A class for managing and interacting with chats in Messages.app
New in version 0.0.1.
Attributes:
The account that is participating in the chat.
The unique identifier for the chat.
The name of the chat as it appears in the chat list.
Methods:
Gets a clipboard-codable representation of the chat.
participants
([filter])Returns a list of participants, as PyXA objects, matching the given filter.
send
(message)Sends a message to the chat.
- property account: XAMessagesAccount
The account that is participating in the chat.
New in version 0.0.1.
- get_clipboard_representation() str [source]
Gets a clipboard-codable representation of the chat.
When the clipboard content is set to a chat, the chat’s name is added to the clipboard.
- Returns:
The name of the chat
- Return type:
str
New in version 0.0.8.
- property id: str
The unique identifier for the chat.
New in version 0.0.1.
- property name: str
The name of the chat as it appears in the chat list.
New in version 0.0.1.
- participants(filter: dict | None = None) XAMessagesParticipantList [source]
Returns a list of participants, as PyXA objects, matching the given filter.
New in version 0.0.4.
- send(message)[source]
Sends a message to the chat.
_extended_summary_
- Parameters:
message (_type_) – _description_
- Example 1:
Send an SMS to a chat based on the chat ID
>>> import PyXA >>> app = PyXA.Application("Messages") >>> chat = app.chats().by_id("SMS;-;+11234567891") >>> chat.send("Hello!")
New in version 0.0.4.
- class PyXA.apps.Messages.XAMessagesChatList(properties: dict, filter: dict | None = None)[source]
Bases:
XAList
,XAClipboardCodable
A wrapper around a list of chats that employs fast enumeration techniques.
All properties of chats can be called as methods on the wrapped list, returning a list containing each chat’s value for the property.
New in version 0.0.4.
Methods:
account
()by_account
(account)by_id
(id)by_name
(name)by_participants
(participants)Gets a clipboard-codable representation of each chat in the list.
id
()name
()- account() XAMessagesAccountList [source]
- by_account(account: XAMessagesAccount) XAMessagesChat [source]
- by_id(id: str) XAMessagesChat [source]
- by_name(name: str) XAMessagesChat [source]
- by_participants(participants: list[XAMessagesParticipant]) XAMessagesChat [source]
- get_clipboard_representation() list[str] [source]
Gets a clipboard-codable representation of each chat in the list.
When the clipboard content is set to a list of chats, each chat’s name is added to the clipboard.
- Returns:
The list of chat names
- Return type:
list[str]
New in version 0.0.8.
- participants() list[XAMessagesParticipantList] [source]
- class PyXA.apps.Messages.XAMessagesDocument(properties)[source]
Bases:
XAObject
A class for managing and interacting with documents in Messages.app.
New in version 0.0.4.
Attributes:
The location of the document on the disk, if one exists.
Whether the document has been modified since its last save.
The title of the document.
- property file: str
The location of the document on the disk, if one exists.
New in version 0.0.4.
- property modified: bool
Whether the document has been modified since its last save.
New in version 0.0.4.
- property name: str
The title of the document.
New in version 0.0.4.
- class PyXA.apps.Messages.XAMessagesDocumentList(properties: dict, filter: dict | None = None)[source]
Bases:
XAList
A wrapper around a list of 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:
by_file
(file)by_modified
(modified)by_name
(name)file
()modified
()name
()- by_file(file: str) XAMessagesDocument | None [source]
- by_modified(modified: bool) XAMessagesDocument | None [source]
- by_name(name: str) XAMessagesDocument | None [source]
- class PyXA.apps.Messages.XAMessagesFileTransfer(properties)[source]
Bases:
XAObject
,XAClipboardCodable
A class for managing and interacting with file transfers in Messages.app
New in version 0.0.1.
Attributes:
The account on which the file transfer is taking place.
The direction that the file is being sent.
The local page to the file being transferred.
The number of bytes that have been transferred.
The total size of the file transfer in bytes.
The unique identifier for the file transfer.
The name of the file.
The other participant in the file transfer.
The date and time that the file transfer started.
The current status of the file transfer.
Methods:
Gets a clipboard-codable representation of the file transfer.
- property account: XAMessagesAccount
The account on which the file transfer is taking place.
- property direction: MessageDirection
The direction that the file is being sent.
- property file_progress: int
The number of bytes that have been transferred.
- property file_size: int
The total size of the file transfer in bytes.
- get_clipboard_representation() list[NSURL] [source]
Gets a clipboard-codable representation of the file transfer.
When the clipboard content is set to a file transfer, the path of the file transfer is added to the clipboard.
- Returns:
The file path of the file transfer
- Return type:
list[AppKit.NSURL]
New in version 0.0.8.
- property id: str
The unique identifier for the file transfer.
- property name: str
The name of the file.
- property participant: XAMessagesParticipant
The other participant in the file transfer.
- property started: datetime
The date and time that the file transfer started.
- property transfer_status: TransferStatus
The current status of the file transfer.
- class PyXA.apps.Messages.XAMessagesFileTransferList(properties: dict, filter: dict | None = None)[source]
Bases:
XAList
,XAClipboardCodable
A wrapper around a list of file transfers that employs fast enumeration techniques.
All properties of file transfers can be called as methods on the wrapped list, returning a list containing each file transfer’s value for the property.
New in version 0.0.4.
Methods:
account
()by_account
(account)by_direction
(direction)by_file_path
(file_path)by_file_progress
(file_progress)by_file_size
(file_size)by_id
(id)by_name
(name)by_participant
(participant)by_started
(started)by_transfer_status
(transfer_status)filter
(filter[, comparison_operation, ...])Filters the list by the given parameters.
Gets a clipboard-codable representation of each file transfer in the list.
id
()name
()started
()- account() XAMessagesAccountList [source]
- by_account(account: XAMessagesAccount) XAMessagesFileTransfer [source]
- by_direction(direction: MessageDirection) XAMessagesFileTransfer [source]
- by_file_path(file_path: XAPath) XAMessagesFileTransfer [source]
- by_file_progress(file_progress: int) XAMessagesFileTransfer [source]
- by_file_size(file_size: int) XAMessagesFileTransfer [source]
- by_id(id: str) XAMessagesFileTransfer [source]
- by_name(name: str) XAMessagesFileTransfer [source]
- by_participant(participant: XAMessagesParticipant) XAMessagesFileTransfer [source]
- by_started(started: bool) XAMessagesFileTransfer [source]
- by_transfer_status(transfer_status: TransferStatus) XAMessagesFileTransfer [source]
- direction() list[MessageDirection] [source]
- 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:
- 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.
- get_clipboard_representation() list[str | NSURL] [source]
Gets a clipboard-codable representation of each file transfer in the list.
When the clipboard content is set to a list of file transfers, each file transfer’s file path URL is added to the clipboard.
- Returns:
The list of file path URLs
- Return type:
list[AppKit.NSURL]
New in version 0.0.8.
- participant() XAMessagesParticipantList [source]
- transfer_status() list[TransferStatus] [source]
- class PyXA.apps.Messages.XAMessagesParticipant(properties)[source]
Bases:
XAObject
,XAClipboardCodable
A class for managing and interacting with chat participants in Messages.app
New in version 0.0.1.
Attributes:
The account for the participant.
The first name of the participant, taken from their contact card (if available).
The full name of the participant, taken from their contact card (if available).
The participant's handle.
The unique identifier for the participant.
The last name of the participant, taken from their contact card (if available).
The name of the participant as it appears in the participant list
Methods:
Gets a clipboard-codable representation of the participant.
- property account: XAMessagesAccount
The account for the participant.
New in version 0.0.1.
- property first_name: str
The first name of the participant, taken from their contact card (if available).
New in version 0.0.1.
- property full_name: str
The full name of the participant, taken from their contact card (if available).
New in version 0.0.1.
- get_clipboard_representation() str [source]
Gets a clipboard-codable representation of the participant.
When the clipboard content is set to a participant, the full name of the participant is added to the clipboard.
- Returns:
The participant’s full name
- Return type:
str
New in version 0.0.8.
- property handle: str
The participant’s handle.
New in version 0.0.1.
- property id: str
The unique identifier for the participant.
New in version 0.0.1.
- property last_name: str
The last name of the participant, taken from their contact card (if available).
New in version 0.0.1.
- property name: str
The name of the participant as it appears in the participant list
New in version 0.0.1.
- class PyXA.apps.Messages.XAMessagesParticipantList(properties: dict, filter: dict | None = None)[source]
Bases:
XAList
,XAClipboardCodable
A wrapper around a list of participants that employs fast enumeration techniques.
All properties of participants can be called as methods on the wrapped list, returning a list containing each participant’s value for the property.
New in version 0.0.4.
Methods:
account
()by_account
(account)by_first_name
(first_name)by_full_name
(full_name)by_handle
(handle)by_id
(id)by_last_name
(last_name)by_name
(name)Gets a clipboard-codable representation of each participant in the list.
handle
()id
()name
()- account() XAMessagesAccountList [source]
- by_account(account: XAMessagesAccount) XAMessagesParticipant | None [source]
- by_first_name(first_name: str) XAMessagesParticipant | None [source]
- by_full_name(full_name: str) XAMessagesParticipant | None [source]
- by_handle(handle: str) XAMessagesParticipant | None [source]
- by_id(id: str) XAMessagesParticipant | None [source]
- by_last_name(last_name: str) XAMessagesParticipant | None [source]
- by_name(name: str) XAMessagesParticipant | None [source]
- get_clipboard_representation() list[str] [source]
Gets a clipboard-codable representation of each participant in the list.
When the clipboard content is set to a list of participants, each participant’s full name is added to the clipboard.
- Returns:
The list of participant names
- Return type:
list[str]
New in version 0.0.8.
- class PyXA.apps.Messages.XAMessagesWindow(properties)[source]
Bases:
XASBWindow
A class for managing and interacting with Messages windows.
New in version 0.0.4.
Attributes:
The bounding rectangle of the window.
Whether the window has a close button.
The unique identifier for the window.
The index of the window in the front-to-back ordering.
Whether the window can be minimized.
Whether the window is currently minimized.
The title of the window.
Whether the window can be resized.
Whether the window is currently visible.
Whether the window can be zoomed.
Whether the window is currently zoomed.
- property bounds: tuple[int, int, int, int]
The bounding rectangle of the window.
New in version 0.0.4.
- property closeable: bool
Whether the window has a close button.
New in version 0.0.4.
- property document: XAMessagesDocument
- property id: int
The unique identifier for the window.
New in version 0.0.4.
- property index: int
The index of the window in the front-to-back ordering.
New in version 0.0.4.
- property miniaturizable: bool
Whether the window can be minimized.
New in version 0.0.4.
- property miniaturized: bool
Whether the window is currently minimized.
New in version 0.0.4.
- property name: str
The title of the window.
New in version 0.0.4.
- property resizable: bool
Whether the window can be resized.
New in version 0.0.4.
- property visible: bool
Whether the window is currently visible.
New in version 0.0.4.
- property zoomable: bool
Whether the window can be zoomed.
New in version 0.0.4.
- property zoomed: bool
Whether the window is currently zoomed.
New in version 0.0.4.