diff --git a/MANIFEST.in b/MANIFEST.in
index 006a72b..dccd76b 100644
--- a/MANIFEST.in
+++ b/MANIFEST.in
@@ -1 +1,2 @@
-recursive-include PyXA/apps *
\ No newline at end of file
+recursive-include PyXA/apps *
+recursive-include PyXA/Additions *
\ No newline at end of file
diff --git a/PyXA/Additions/__init__.py b/PyXA/Additions/__init__.py
new file mode 100644
index 0000000..e69de29
diff --git a/PyXA/XABase.py b/PyXA/XABase.py
index d74b15c..50bc879 100644
--- a/PyXA/XABase.py
+++ b/PyXA/XABase.py
@@ -3815,24 +3815,6 @@ def text(self) -> 'XAText':
def text(self, text: str):
self.set_property("text", text)
- def set_text(self, new_text: str) -> 'XATextDocument':
- """Sets the text of the document.
-
- :param new_text: The new text of the document
- :type new_text: str
- :return: A reference to the document object.
- :rtype: XATextDocument
-
- .. seealso:: :func:`prepend`, :func:`append`
-
- .. deprecated:: 0.1.0
- Directly set the text attribute instead.
-
- .. versionadded:: 0.0.1
- """
- self.set_property("text", new_text)
- return self
-
def prepend(self, text: str) -> 'XATextDocument':
"""Inserts the provided text at the beginning of the document.
diff --git a/docs/.buildinfo b/docs/.buildinfo
index c58298a..decc719 100644
--- a/docs/.buildinfo
+++ b/docs/.buildinfo
@@ -1,4 +1,4 @@
# Sphinx build info version 1
# This file hashes the configuration used when building these files. When it is not found, a full rebuild will be done.
-config: e66641e5564ff243b6ce56fa6327a42b
+config: a9ded26fdd0bd00c428ae81c71202a6c
tags: 645f666f9bcd5a90fca523b33c5a78b7
diff --git a/docs/_images/PyXALogoTransparent.png b/docs/_images/PyXALogoTransparent.png
new file mode 100644
index 0000000..6d8a9aa
Binary files /dev/null and b/docs/_images/PyXALogoTransparent.png differ
diff --git a/docs/_modules/PyXA/PyXA 2.html b/docs/_modules/PyXA/PyXA 2.html
new file mode 100644
index 0000000..c62c626
--- /dev/null
+++ b/docs/_modules/PyXA/PyXA 2.html
@@ -0,0 +1,541 @@
+
+
+
+
+
+ PyXA.PyXA — PyXA 0.0.9 documentation
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+fromdatetimeimportdatetime
+fromtimeimportsleep
+fromtypingimportAny,Callable,List,Union
+importimportlib
+
+importAppKit
+fromQuartzimportCGWindowListCopyWindowInfo,kCGNullWindowID,kCGWindowListOptionAll
+
+from.XABaseimport*
+fromPyXAimportXABaseScriptable
+from.appsimportapplication_classes
+
+from.XAErrorsimportApplicationNotFoundError
+
+VERSION="0.1.0"#: The installed version of PyXA
+
+supported_applications:List[str]=list(application_classes.keys())#: A list of names of supported scriptable applications
+
+
[docs]classXAApplicationList(XAList):
+ """A wrapper around a list of applications.
+
+ .. versionadded:: 0.0.5
+ """
+ def__init__(self,properties:dict,filter:Union[dict,None]=None):
+ super().__init__(properties,XAApplication,filter)
+
+ iffilterisnotNone:
+ self.xa_elem=XAPredicate().from_dict(filter).evaluate(self.xa_elem)
+
+
[docs]deffirst(self)->XAObject:
+ """Retrieves the first element of the list as a wrapped PyXA application object.
+
+ :return: The wrapped object
+ :rtype: XAObject
+
+ .. versionadded:: 0.0.5
+ """
+ returnself.__getitem__(0)
+
+
[docs]deflast(self)->XAObject:
+ """Retrieves the last element of the list as a wrapped PyXA application object.
+
+ :return: The wrapped object
+ :rtype: XAObject
+
+ .. versionadded:: 0.0.5
+ """
+ returnself.__getitem__(-1)
+
+
[docs]defpop(self,index:int=-1)->XAObject:
+ """Removes the application at the specified index from the list and returns it.
+
+ .. versionadded:: 0.0.5
+ """
+ removed=self.xa_elem.lastObject()
+ self.xa_elem.removeLastObject()
+ app_name=removed["kCGWindowOwnerName"]
+ returnApplication(app_name)
+
+ def__getitem__(self,key:Union[int,slice]):
+ """Retrieves the wrapped application object(s) at the specified key."""
+ ifisinstance(key,slice):
+ arr=AppKit.NSArray.alloc().initWithArray_([self.xa_elem[index]forindexinrange(key.start,key.stop,key.stepor1)])
+ returnself._new_element(arr,self.__class__)
+ app_name=self.xa_elem[key]["kCGWindowOwnerName"]
+ returnApplication(app_name)
+
+
[docs]defbundle_identifier(self)->List[str]:
+ """Gets the bundle identifier of every application in the list.
+
+ :return: The list of application bundle identifiers
+ :rtype: List[str]
+
+ .. versionadded:: 0.0.5
+ """
+ return[app.bundle_identifierforappinself]
+
+
[docs]defbundle_url(self)->List[XAURL]:
+ """Gets the bundle URL of every application in the list.
+
+ :return: The list of application bundle URLs
+ :rtype: List[XAURL]
+
+ .. versionadded:: 0.0.5
+ """
+ return[XAURL(app.bundle_url)forappinself]
+
+
[docs]defexecutable_url(self)->List[XAURL]:
+ """Gets the executable URL of every application in the list.
+
+ :return: The list of application executable URLs
+ :rtype: List[XAURL]
+
+ .. versionadded:: 0.0.5
+ """
+ return[XAURL(app.executable_url)forappinself]
+
+
[docs]deflaunch_date(self)->List[datetime]:
+ """Gets the launch date of every application in the list.
+
+ :return: The list of application launch dates
+ :rtype: List[str]
+
+ .. versionadded:: 0.0.5
+ """
+ return[app.launch_dateforappinself]
+
+
[docs]deflocalized_name(self)->List[str]:
+ """Gets the localized name of every application in the list.
+
+ :return: The list of application localized names
+ :rtype: List[str]
+
+ .. versionadded:: 0.0.5
+ """
+ return[x.get("kCGWindowOwnerName")forxinself.xa_elem]
+
+
[docs]defprocess_identifier(self)->List[str]:
+ """Gets the process identifier of every application in the list.
+
+ :return: The list of application process identifiers
+ :rtype: List[str]
+
+ .. versionadded:: 0.0.5
+ """
+ return[x.get("kCGWindowOwnerPID")forxinself.xa_elem]
[docs]defterminate(self):
+ """Quits (terminates) all applications in the list. Synonymous with :func:`quit`.
+
+ :Example 1: Terminate all visible running applications
+
+ >>> import PyXA
+ >>> apps = PyXA.running_applications()
+ >>> apps.terminate()
+
+ .. versionadded:: 0.0.5
+ """
+ forappinself:
+ app.terminate()
+
+
[docs]defquit(self):
+ """Quits (terminates) all applications in the list. Synonymous with :func:`terminate`.
+
+ :Example 1: Quit all visible running applications
+
+ >>> import PyXA
+ >>> apps = PyXA.running_applications()
+ >>> apps.quit()
+
+ .. versionadded:: 0.0.5
+ """
+ forappinself:
+ app.terminate()
+
+
[docs]defwindows(self)->'XACombinedWindowList':
+ """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.
+
+ :return: A list containing both scriptable and non-scriptable windows
+ :rtype: XACombinedWindowList
+
+ :Example:
+
+ >>> import PyXA
+ >>> windows = PyXA.running_applications().windows()
+ >>> windows.collapse()
+ >>> sleep(1)
+ >>> windows.uncollapse()
+
+ .. versionadded:: 0.0.5
+ """
+ ls=[]
+ forappinself:
+ ls.extend(app.windows().xa_elem)
+ ls=AppKit.NSArray.alloc().initWithArray_(ls)
+ window_list=self._new_element(ls,XACombinedWindowList)
+ returnwindow_list
[docs]classApplication(XAObject):
+ shared_app=AppKit.NSApplication.sharedApplication()
+ workspace=AppKit.NSWorkspace.sharedWorkspace()
+ app_paths:List[str]=[]#: A list containing the path to each application
+
+ def__init__(self,app_name:str):
+ """Creates a new application object.
+
+ :param app_name: The name of the target application
+ :type app_name: str
+
+ .. versionadded:: 0.1.0
+ """
+ # Elevate to XAApplication
+ new_self=self.__get_application(app_name)
+ self.__class__=new_self.__class__
+ self.__dict__.update(new_self.__dict__)
+
+ def__xa_get_path_to_app(self,app_identifier:str)->str:
+ self.__xa_load_app_paths()
+ forpathinself.app_paths:
+ ifapp_identifier.lower()inpath.lower():
+ returnpath
+
+ raiseApplicationNotFoundError(app_identifier)
+
+ def__xa_load_app_paths(self):
+ ifself.app_paths==[]:
+ search=XASpotlight()
+ search.predicate="kMDItemContentType == 'com.apple.application-bundle'"
+ search.run()
+ self.app_paths=[x.pathforxinsearch.results]
+
+ def__get_application(self,app_identifier:str)->XAApplication:
+ """Retrieves a PyXA application object representation of the target application without launching or activating the application.
+
+ :param app_identifier: The name of the application to get an object of.
+ :type app_identifier: str
+ :return: A PyXA application object referencing the target application.
+ :rtype: XAApplication
+
+ .. versionadded:: 0.0.1
+ """
+ app_identifier_l=app_identifier.lower()
+
+ def_match_open_app(obj,index,stop):
+ return(obj.localizedName().lower()==app_identifier_l,stop)
+
+ idx_set=self.workspace.runningApplications().indexesOfObjectsPassingTest_(_match_open_app)
+ ifidx_set.count()==1:
+ index=idx_set.firstIndex()
+ app=self.workspace.runningApplications()[index]
+ properties={
+ "parent":None,
+ "appspace":self.shared_app,
+ "workspace":self.workspace,
+ "element":app,
+ "appref":app,
+ }
+
+ app_obj=application_classes.get(app_identifier_l,XAApplication)
+ ifisinstance(app_obj,tuple):
+ module=importlib.import_module("PyXA.apps."+app_obj[0])
+ app_class=getattr(module,app_obj[1],None)
+ ifapp_classisnotNone:
+ application_classes[app_identifier_l]=app_class
+ app=app_class
+ else:
+ raiseNotImplementedError()
+
+ # Check if the app is supported by PyXA
+ app_ref=application_classes.get(app_identifier_l,XAApplication)(properties)
+ returnapp_ref
+
+ app_path=app_identifier
+ ifnotapp_identifier.startswith("/"):
+ app_path=self.__xa_get_path_to_app(app_identifier)
+ bundle=AppKit.NSBundle.alloc().initWithPath_(app_path)
+ url=self.workspace.URLForApplicationWithBundleIdentifier_(bundle.bundleIdentifier())
+
+ config=AppKit.NSWorkspaceOpenConfiguration.alloc().init()
+ config.setActivates_(False)
+ config.setHides_(True)
+
+ app_ref=None
+ def_launch_completion_handler(app,_error):
+ nonlocalapp_ref
+ properties={
+ "parent":None,
+ "appspace":self.shared_app,
+ "workspace":self.workspace,
+ "element":app,
+ "appref":app,
+ }
+
+ app_obj=application_classes.get(app_identifier_l,None)
+ ifisinstance(app_obj,tuple):
+ module=importlib.import_module("PyXA.apps."+app_obj[0])
+ app_class=getattr(module,app_obj[1],None)
+ ifapp_classisnotNone:
+ application_classes[app_identifier_l]=app_class
+ app=app_class
+ else:
+ raiseNotImplementedError()
+
+ app_ref=application_classes.get(app_identifier_l,XAApplication)(properties)
+
+ self.workspace.openApplicationAtURL_configuration_completionHandler_(url,config,_launch_completion_handler)
+ whileapp_refisNone:
+ sleep(0.01)
+ returnapp_ref
+
+
+
+
+
[docs]classXACombinedWindowList(XAList):
+ """A wrapper around a combined list of both scriptable and non-scriptable windows.
+
+ This class contains methods that specialize to XAWindow and XASBWindow methods as necessary.
+
+ .. versionadded:: 0.0.5
+ """
+ def__init__(self,properties:dict,filter:Union[dict,None]=None):
+ super().__init__(properties,XAWindow,filter)
+
+
[docs]defcollapse(self)->'XACombinedWindowList':
+ """Collapses all windows in the list.
+
+ :return: The window list object
+ :rtype: XACombinedWindowList
+
+ :Example 1: Collapse all windows for all currently visible running applications
+
+ >>> import PyXA
+ >>> apps = PyXA.running_applications()
+ >>> apps.windows().collapse()
+
+ .. versionadded:: 0.0.5
+ """
+ forwindowinself:
+ ifnothasattr(window.xa_elem,"buttons"):
+ # Specialize to XASBWindow
+ window=self.xa_prnt._new_element(window.xa_elem,XABaseScriptable.XASBWindow)
+ window.collapse()
+ returnself
+
+
[docs]defuncollapse(self)->'XACombinedWindowList':
+ """Uncollapses all windows in the list.
+
+ :return: The window list object
+ :rtype: XACombinedWindowList
+
+ .. versionadded:: 0.1.0
+ """
+ forwindowinself:
+ ifnothasattr(window.xa_elem,"buttons"):
+ # Specialize to XASBWindow
+ window=self.xa_prnt._new_element(window.xa_elem,XABaseScriptable.XASBWindow)
+ window.uncollapse()
+ returnself
+
+
+
+
+
[docs]defrunning_applications()->List[XAApplication]:
+ """Gets PyXA references to all currently visible (not hidden or minimized) running applications whose app bundles are stored in typical application directories.
+
+ :return: A list of PyXA application objects.
+ :rtype: List[XAApplication]
+
+ :Example 1: Get the name of each running application
+
+ >>> import PyXA
+ >>> apps = PyXA.running_applications()
+ >>> print(apps.localized_name())
+ ['GitHub Desktop', 'Safari', 'Code', 'Terminal', 'Notes', 'Messages', 'TV']
+
+ .. versionadded:: 0.0.1
+ """
+ windows=CGWindowListCopyWindowInfo(kCGWindowListOptionAll,kCGNullWindowID)
+ ls=XAPredicate.evaluate_with_format(windows,"kCGWindowIsOnscreen == 1 && kCGWindowLayer == 0")
+ properties={
+ "appspace":AppKit.NSApplication.sharedApplication(),
+ "workspace":AppKit.NSWorkspace.sharedWorkspace(),
+ "element":ls,
+ }
+ arr=XAApplicationList(properties)
+ returnarr
+
+
+
+
+
[docs]defcurrent_application()->XAApplication:
+ """Retrieves a PyXA representation of the frontmost application.
+
+ :return: A PyXA application object referencing the current application.
+ :rtype: XAApplication
+
+ .. versionadded:: 0.0.1
+ """
+ returnApplication(AppKit.NSWorkspace.sharedWorkspace().frontmostApplication().localizedName())
+
+
+
+
+
[docs]defapplication(app_identifier:str)->XAApplication:
+ """Retrieves a PyXA application object representation of the target application without launching or activating the application.
+
+ :param app_identifier: The name of the application to get an object of.
+ :type app_identifier: str
+ :return: A PyXA application object referencing the target application.
+ :rtype: XAApplication
+
+ .. deprecated:: 0.1.0
+
+ Use :class:`Application` instead.
+
+ .. versionadded:: 0.0.1
+ """
+ returnApplication(app_identifier)
+
+
+
+
+
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/docs/_modules/PyXA/PyXA.html b/docs/_modules/PyXA/PyXA.html
index 0b076cd..ee03f46 100644
--- a/docs/_modules/PyXA/PyXA.html
+++ b/docs/_modules/PyXA/PyXA.html
@@ -3,7 +3,7 @@
- PyXA.PyXA — PyXA 0.0.9 documentation
+ PyXA.PyXA — PyXA 0.1.0 documentation
@@ -14,7 +14,9 @@
+
+
@@ -69,185 +71,22 @@
Source code for PyXA.PyXA
fromdatetimeimportdatetime
-fromenumimportEnum
-importosfromtimeimportsleepfromtypingimportAny,Callable,List,UnionimportimportlibimportAppKit
-fromAppKitimport(
- NSWorkspace,
- NSApplication,
- NSPasteboard,
- NSArray,
- NSPasteboardTypeString,
- NSAppleScript,
-)
-fromFoundationimportNSURL,NSBundle
-
fromQuartzimportCGWindowListCopyWindowInfo,kCGNullWindowID,kCGWindowListOptionAllfrom.XABaseimport*
-from.XABaseScriptableimport*
-from.XAErrorsimportApplicationNotFoundError
-from.appsimportapplication_classesfromPyXAimportXABaseScriptable
+from.appsimportapplication_classes
-VERSION="0.0.9"
-DATE=str(datetime.now())
-
-appspace=NSApplication.sharedApplication()
-workspace=NSWorkspace.sharedWorkspace()
-app_paths:List[str]=[]
-
-scriptable_applications:List[str]=list(application_classes.keys())#: A list of names of scriptable applications
-
-# class _staticproperty(staticmethod):
-# def __get__(self, *_):
-# return self.__func__()
-
-# class Application(XAObject):
-# shared_app = NSApplication.sharedApplication()
-# workspace = NSWorkspace.sharedWorkspace()
-# app_paths: List[str] = [] #: A list containing the path to each application
-# current_application: XAApplication #: The currently active application
-
-# def __init__(self, app_identifier: str):
-# """Creates an application object.
-
-# :param app_identifier: The name of an application
-# :type app_identifier: str
-
-# .. versionadded:: 0.0.9
-# """
-# self.app =
-
-# def _get_path_to_app(app_identifier: str) -> str:
-# Application._xa_load_app_paths()
-# for path in app_paths:
-# if app_identifier in path:
-# return path
-
-# raise ApplicationNotFoundError(app_identifier)
-
-# def _xa_load_app_paths():
-# if Application.app_paths == []:
-# search = XASpotlight()
-# search.predicate = "kMDItemContentType == 'com.apple.application-bundle'"
-# search.run()
-# app_paths = [x.path for x in search.results]
-
-# @_staticproperty
-# def current_application() -> XAApplication:
-# return application(workspace.frontmostApplication().localizedName())
-
-# def _xa_get_open_app(app_identifier: str):
-# def _match_open_app(obj, index, stop):
-# return (obj.localizedName() == app_identifier, stop)
-
-# idx_set = workspace.runningApplications().indexesOfObjectsPassingTest_(_match_open_app)
-# if idx_set.count() == 1:
-# index = idx_set.firstIndex()
-# app = workspace.runningApplications()[index]
-# return Application._xa_get_app_ref(app_identifier.lower(), app)
-
-# def _xa_get_app_ref(app_identifier: str, app_object):
-# properties = {
-# "parent": None,
-# "appspace": Application.shared_app,
-# "workspace": Application.workspace,
-# "element": app_object,
-# "appref": app_object,
-# }
-
-# app_obj = application_classes.get(app_identifier, XAApplication)
-# if isinstance(app_obj, tuple):
-# module = importlib.import_module("PyXA.apps." + app_obj[0])
-# app_class = getattr(module, app_obj[1], None)
-# if app_class is not None:
-# application_classes[app_identifier] = app_class
-# app = app_class
-# else:
-# raise NotImplementedError()
-
-# return application_classes.get(app_identifier, XAApplication)(properties)
-
-# def _xa_get_application(app_identifier: str) -> XAApplication:
-# """Retrieves a PyXA application object representation of the target application without launching or activating the application.
-
-# :param app_identifier: The name of the application to get an object of.
-# :type app_identifier: str
-# :return: A PyXA application object referencing the target application.
-# :rtype: XAApplication
-
-# .. versionadded:: 0.0.9
-# """
-# open_app = Application._xa_get_open_app(app_identifier)
-# if open_app is not None:
-# return open_app
-
-# app_path = _get_path_to_app(app_identifier)
-# bundle = NSBundle.alloc().initWithPath_(app_path)
-# url = workspace.URLForApplicationWithBundleIdentifier_(bundle.bundleIdentifier())
-
-# config = AppKit.NSWorkspaceOpenConfiguration.alloc().init()
-# config.setActivates_(False)
-# config.setHides_(True)
-
-# app_ref = None
-# def _launch_completion_handler(app, _error):
-# nonlocal app_ref
-# app_ref = Application._xa_get_app_ref(app_identifier.lower(), app)
-
-# workspace.openApplicationAtURL_configuration_completionHandler_(url, config, _launch_completion_handler)
-# while app_ref is None:
-# sleep(0.01)
-# return app_ref
-
-
-def_xa_get_path_to_app(app_identifier:str)->str:
- _xa_load_app_paths()
- forpathinapp_paths:
- ifapp_identifierinpath:
- returnpath
-
- raiseApplicationNotFoundError(app_identifier)
-
-def_xa_load_app_paths():
- globalapp_paths
- ifapp_paths==[]:
- search=XASpotlight()
- search.predicate="kMDItemContentType == 'com.apple.application-bundle'"
- search.run()
- app_paths=[x.pathforxinsearch.results]
-
-
-
[docs]defrunning_applications()->List[XAApplication]:
- """Gets PyXA references to all currently visible (not hidden or minimized) running applications whose app bundles are stored in typical application directories.
-
- :return: A list of PyXA application objects.
- :rtype: List[XAApplication]
+from.XAErrorsimportApplicationNotFoundError
- :Example 1: Get the name of each running application
-
- >>> import PyXA
- >>> apps = PyXA.running_applications()
- >>> print(apps.localized_name())
- ['GitHub Desktop', 'Safari', 'Code', 'Terminal', 'Notes', 'Messages', 'TV']
-
- .. versionadded:: 0.0.1
- """
- windows=CGWindowListCopyWindowInfo(kCGWindowListOptionAll,kCGNullWindowID)
- ls=XAPredicate.evaluate_with_format(windows,"kCGWindowIsOnscreen == 1 && kCGWindowLayer == 0")
- properties={
- "appspace":appspace,
- "workspace":workspace,
- "element":ls,
- }
- arr=XAApplicationList(properties)
- returnarr
+VERSION="0.1.0"#: The installed version of PyXA
+supported_applications:List[str]=list(application_classes.keys())#: A list of names of supported scriptable applications
[docs]classXAApplicationList(XAList):"""A wrapper around a list of applications.
@@ -288,7 +127,7 @@
[docs]defbundle_identifier(self)->List[str]:
+ """Gets the bundle identifier of every application in the list.
+
+ :return: The list of application bundle identifiers
+ :rtype: List[str]
+
+ .. versionadded:: 0.0.5
+ """return[app.bundle_identifierforappinself]
[docs]defbundle_url(self)->List[XAURL]:
+ """Gets the bundle URL of every application in the list.
+
+ :return: The list of application bundle URLs
+ :rtype: List[XAURL]
-
[docs]defexecutable_url(self)->List[XAURL]:
+ """Gets the executable URL of every application in the list.
+
+ :return: The list of application executable URLs
+ :rtype: List[XAURL]
+
+ .. versionadded:: 0.0.5
+ """
+ return[XAURL(app.executable_url)forappinself]
[docs]deflaunch_date(self)->List[datetime]:
+ """Gets the launch date of every application in the list.
+
+ :return: The list of application launch dates
+ :rtype: List[str]
+
+ .. versionadded:: 0.0.5
+ """return[app.launch_dateforappinself]
[docs]deflocalized_name(self)->List[str]:
+ """Gets the localized name of every application in the list.
+
+ :return: The list of application localized names
+ :rtype: List[str]
+
+ .. versionadded:: 0.0.5
+ """return[x.get("kCGWindowOwnerName")forxinself.xa_elem]
[docs]defprocess_identifier(self)->List[str]:
+ """Gets the process identifier of every application in the list.
+
+ :return: The list of application process identifiers
+ :rtype: List[str]
+
+ .. versionadded:: 0.0.5
+ """return[x.get("kCGWindowOwnerPID")forxinself.xa_elem]
[docs]defcollapse(self)->'XACombinedWindowList':"""Collapses all windows in the list.
+ :return: The window list object
+ :rtype: XACombinedWindowList
+
:Example 1: Collapse all windows for all currently visible running applications >>> import PyXA
@@ -428,7 +449,53 @@
Source code for PyXA.PyXA
ifnothasattr(window.xa_elem,"buttons"):# Specialize to XASBWindowwindow=self.xa_prnt._new_element(window.xa_elem,XABaseScriptable.XASBWindow)
- window.collapse()
+ window.collapse()
+ returnself
+
+
[docs]defuncollapse(self)->'XACombinedWindowList':
+ """Uncollapses all windows in the list.
+
+ :return: The window list object
+ :rtype: XACombinedWindowList
+
+ .. versionadded:: 0.1.0
+ """
+ forwindowinself:
+ ifnothasattr(window.xa_elem,"buttons"):
+ # Specialize to XASBWindow
+ window=self.xa_prnt._new_element(window.xa_elem,XABaseScriptable.XASBWindow)
+ window.uncollapse()
+ returnself
+
+
+
+
+
[docs]defrunning_applications()->List[XAApplication]:
+ """Gets PyXA references to all currently visible (not hidden or minimized) running applications whose app bundles are stored in typical application directories.
+
+ :return: A list of PyXA application objects.
+ :rtype: List[XAApplication]
+
+ :Example 1: Get the name of each running application
+
+ >>> import PyXA
+ >>> apps = PyXA.running_applications()
+ >>> print(apps.localized_name())
+ ['GitHub Desktop', 'Safari', 'Code', 'Terminal', 'Notes', 'Messages', 'TV']
+
+ .. versionadded:: 0.0.1
+ """
+ windows=CGWindowListCopyWindowInfo(kCGWindowListOptionAll,kCGNullWindowID)
+ ls=XAPredicate.evaluate_with_format(windows,"kCGWindowIsOnscreen == 1 && kCGWindowLayer == 0")
+ properties={
+ "appspace":AppKit.NSApplication.sharedApplication(),
+ "workspace":AppKit.NSWorkspace.sharedWorkspace(),
+ "element":ls,
+ }
+ arr=XAApplicationList(properties)
+ returnarr
[docs]classXAObject():
+ """A general class for PyXA scripting objects.
+
+ .. seealso:: :class:`XABaseScriptable.XASBObject`
+
+ .. versionadded:: 0.0.1
+ """
+ def__init__(self,properties:dict=None):
+ """Instantiates a PyXA scripting object.
+
+ :param properties: A dictionary of properties to assign to this object.
+ :type properties: dict, optional
+
+ .. versionchanged:: 0.0.3
+ Removed on-the-fly creation of class attributes. All objects should concretely define their properties.
+
+ .. versionadded:: 0.0.1
+ """
+ ifpropertiesisnotNone:
+ self.xa_prnt=properties.get("parent",None)
+ self.xa_apsp=properties.get("appspace",None)
+ self.xa_wksp=properties.get("workspace",None)
+ self.xa_elem=properties.get("element",None)
+ self.xa_scel=properties.get("scriptable_element",None)
+ self.xa_aref=properties.get("appref",None)
+ self.xa_sevt=properties.get("system_events",SBApplication.alloc().initWithBundleIdentifier_("com.apple.systemevents"))
+
+ self.properties:dict#: The scriptable properties dictionary for the object
+
+ def_exec_suppresed(self,f:Callable[...,Any],*args:Any)->Any:
+ """Silences unwanted and otherwise unavoidable warning messages.
+
+ Taken from: https://stackoverflow.com/a/3946828
+
+ :param f: The function to execute
+ :type f: Callable[...]
+ :param args: The parameters to pass to the specified function
+ :type args: Any
+ :raises error: Any exception that occurs while trying to run the specified function
+ :return: The value returned by the specified function upon execution
+ :rtype: Any
+
+ .. versionadded:: 0.0.2
+ """
+ error=None
+ value=None
+
+ old_stderr=os.dup(sys.stderr.fileno())
+ fd=os.open('/dev/null',os.O_CREAT|os.O_WRONLY)
+ os.dup2(fd,sys.stderr.fileno())
+ try:
+ value=f(*args)
+ exceptExceptionase:
+ error=e
+ os.dup2(old_stderr,sys.stderr.fileno())
+
+ iferrorisnotNone:
+ raiseerror
+ returnvalue
+
+ def_new_element(self,obj:AppKit.NSObject,obj_class:type='XAObject',*args:list[Any])->'XAObject':
+ """Wrapper for creating a new PyXA object.
+
+ :param folder_obj: The Objective-C representation of an object.
+ :type folder_obj: NSObject
+ :return: The PyXA representation of the object.
+ :rtype: XAObject
+
+ .. versionadded:: 0.0.1
+ """
+ properties={
+ "parent":self,
+ "appspace":getattr(self,"xa_apsp",None),
+ "workspace":getattr(self,"xa_wksp",None),
+ "element":obj,
+ "appref":getattr(self,"xa_aref",None),
+ "system_events":getattr(self,"xa_sevt",None),
+ }
+ returnobj_class(properties,*args)
+
+ def_spawn_thread(self,function:Callable[...,Any],args:Union[list[Any],None]=None,kwargs:Union[list[Any],None]=None,daemon:bool=True)->threading.Thread:
+ """Spawns a new thread running the specified function.
+
+ :param function: The function to run in the new thread
+ :type function: Callable[..., Any]
+ :param args: Arguments to pass to the function
+ :type args: list[Any]
+ :param kwargs: Keyword arguments to pass to the function
+ :type kwargs: list[Any]
+ :param daemon: Whether the thread should be a daemon thread, defaults to True
+ :type daemon: bool, optional
+ :return: The thread object
+ :rtype: threading.Thread
+
+ .. versionadded:: 0.0.9
+ """
+ new_thread=threading.Thread(target=function,args=argsor[],kwargs=kwargsor{},daemon=daemon)
+ new_thread.start()
+ returnnew_thread
+
+
[docs]defhas_element(self)->bool:
+ """Whether this object has an AppleScript/JXA/Objective-C scripting element associated with it.
+
+ :return: True if this object's element attribute is set, False otherwise.
+ :rtype: bool
+
+ .. deprecated:: 0.0.9
+
+ Perform this check manually instead.
+
+ .. versionadded:: 0.0.1
+ """
+ returnself.xa_elemisnotNone
+
+
[docs]defhas_element_properties(self)->bool:
+ """Whether the scripting element associated with this object has properties attached to it.
+
+ :return: True if this object's properties attribute is set, False otherwise.
+ :rtype: bool
+
+ .. deprecated:: 0.0.8
+ All elements now have a properties dictionary, even if it is empty.
+
+ .. versionadded:: 0.0.1
+ """
+ returnself.element_properties!=None
+
+
[docs]defset_element(self,element:'XAObject')->'XAObject':
+ """Sets the element attribute to the supplied element and updates the properties attribute accordingly.
+
+ :param element: The new scripting element to reference via the element attribute.
+ :type element: XAObject
+ :return: A reference to this PyXA object.
+ :rtype: XAObject
+
+ .. deprecated:: 0.0.9
+
+ Set the element attribute directly instead.
+
+ .. versionadded:: 0.0.1
+ """
+ self.xa_elem=element
+ returnself
+
+
[docs]defset_properties(self,properties:dict)->'XAObject':
+ """Updates the value of multiple properties of the scripting element associated with this object.
+
+ :param properties: A dictionary defining zero or more property names and updated values as key-value pairs.
+ :type properties: dict
+ :return: A reference to this PyXA object.
+ :rtype: XAObject
+
+ .. versionadded:: 0.0.1
+ """
+ property_dict={}
+ forkeyinproperties:
+ parts=key.split("_")
+ titled_parts=[part.title()forpartinparts[1:]]
+ property_name=parts[0]+"".join(titled_parts)
+ property_dict[property_name]=properties[key]
+ self.xa_elem.setValuesForKeysWithDictionary_(property_dict)
+ returnself
+
+
[docs]defset_property(self,property_name:str,value:Any)->'XAObject':
+ """Updates the value of a single property of the scripting element associated with this object.
+
+ :param property: The name of the property to assign a new value to.
+ :type property: str
+ :param value: The value to assign to the specified property.
+ :type value: Any
+ :return: A reference to this PyXA object.
+ :rtype: XAObject
+
+ .. versionadded:: 0.0.1
+ """
+ parts=property_name.split("_")
+ titled_parts=[part.title()forpartinparts[1:]]
+ property_name=parts[0]+"".join(titled_parts)
+ self.xa_elem.setValue_forKey_(value,property_name)
+ returnself
+
+
[docs]defset_scriptable_property(self,property_name:str,value:Any)->'XAObject':
+ """Updates the value of a single scriptable element property of the scripting element associated with this object.
+
+ :param property: The name of the property to assign a new value to.
+ :type property: str
+ :param value: The value to assign to the specified property.
+ :type value: Any
+ :return: A reference to this PyXA object.
+ :rtype: XAObject
+
+ .. versionadded:: 0.1.0
+ """
+ parts=property_name.split("_")
+ titled_parts=[part.title()forpartinparts[1:]]
+ property_name=parts[0]+"".join(titled_parts)
+ self.xa_scel.setValue_forKey_(value,property_name)
+ returnself
+
+
+
+
+
[docs]classXAApplication(XAObject,XAClipboardCodable):
+ """A general application class for both officially scriptable and non-scriptable applications.
+
+ .. seealso:: :class:`XASBApplication`, :class:`XAWindow`
+
+ .. versionadded:: 0.0.1
+ """
+ def__init__(self,properties):
+ super().__init__(properties)
+ self.xa_wcls=XAWindow
+
+ predicate=AppKit.NSPredicate.predicateWithFormat_("displayedName == %@",self.xa_elem.localizedName())
+ process=self.xa_sevt.processes().filteredArrayUsingPredicate_(predicate)[0]
+
+ properties={
+ "parent":self,
+ "appspace":self.xa_apsp,
+ "workspace":self.xa_wksp,
+ "element":process,
+ "appref":self.xa_aref,
+ "system_events":self.xa_sevt,
+ "window_class":self.xa_wcls
+ }
+ self.xa_prcs=XAProcess(properties)
+
+ self.bundle_identifier:str#: The bundle identifier for the application
+ self.bundle_url:str#: The file URL of the application bundle
+ self.executable_url:str#: The file URL of the application's executable
+ self.frontmost:bool#: Whether the application is the active application
+ self.launch_date:datetime#: The date and time that the application was launched
+ self.localized_name:str#: The application's name
+ self.owns_menu_bar:bool#: Whether the application owns the top menu bar
+ self.process_identifier:str#: The process identifier for the application instance
+
+ self.xa_apsc:appscript.GenericApp
+
+ def__getattr__(self,attr):
+ ifattrinself.__dict__:
+ # If possible, use PyXA attribute
+ returnsuper().__getattribute__(attr)
+ else:
+ # Otherwise, fall back to appscript
+ returngetattr(self.xa_apsc,attr)
+
+ @property
+ defxa_apsc(self)->appscript.GenericApp:
+ returnappscript.app(self.bundle_url.path())
+
+ @property
+ defbundle_identifier(self)->str:
+ returnself.xa_elem.bundleIdentifier()
+
+ @property
+ defbundle_url(self)->str:
+ returnself.xa_elem.bundleURL()
+
+ @property
+ defexecutable_url(self)->str:
+ returnself.xa_elem.executableURL()
+
+ @property
+ deffrontmost(self)->bool:
+ returnself.xa_elem.isActive()
+
+ @frontmost.setter
+ deffrontmost(self,frontmost:bool):
+ iffrontmostisTrue:
+ self.xa_elem.activateWithOptions_(AppKit.NSApplicationActivateIgnoringOtherApps)
+
+ @property
+ deflaunch_date(self)->datetime:
+ returnself.xa_elem.launchDate()
+
+ @property
+ deflocalized_name(self)->str:
+ returnself.xa_elem.localizedName()
+
+ @property
+ defowns_menu_bar(self)->bool:
+ returnself.xa_elem.ownsMenuBar()
+
+ @property
+ defprocess_identifier(self)->str:
+ returnself.xa_elem.processIdentifier()
+
+
[docs]defactivate(self)->'XAApplication':
+ """Activates the application, bringing its window(s) to the front and launching the application beforehand if necessary.
+
+ :return: A reference to the PyXA application object.
+ :rtype: XAApplication
+
+ .. seealso:: :func:`terminate`, :func:`unhide`, :func:`focus`
+
+ .. versionadded:: 0.0.1
+ """
+ self.xa_elem.activateWithOptions_(AppKit.NSApplicationActivateIgnoringOtherApps)
+ returnself
[docs]defget_clipboard_representation(self)->list[Union[str,AppKit.NSURL,AppKit.NSImage]]:
+ """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 different for other applications.
+
+ :return: The clipboard-codable representation
+ :rtype: list[Union[str, AppKit.NSURL, AppKit.NSImage]]
+
+ .. versionadded:: 0.0.8
+ """
+ return[self.xa_elem.localizedName(),self.xa_elem.bundleURL(),self.xa_elem.icon()]
[docs]classSDEFParser(XAObject):
+ def__init__(self,sdef_file:Union['XAPath',str]):
+ ifisinstance(sdef_file,str):
+ sdef_file=XAPath(sdef_file)
+ self.file=sdef_file#: The full path to the SDEF file to parse
+
+ self.app_name=""
+ self.scripting_suites=[]
+
+
[docs]classXAList(XAObject):
+ """A wrapper around NSArray and NSMutableArray objects enabling fast enumeration and lazy evaluation of Objective-C objects.
+
+ .. versionadded:: 0.0.3
+ """
+ def__init__(self,properties:dict,object_class:type=None,filter:Union[dict,None]=None):
+ """Creates an efficient wrapper object around a list of scriptable elements.
+
+ :param properties: PyXA properties passed to this object for utility purposes
+ :type properties: dict
+ :param object_class: _description_, defaults to None
+ :type object_class: type, optional
+ :param filter: A dictionary of properties and values to filter items by, defaults to None
+ :type filter: Union[dict, None], optional
+
+ .. versionchanged:: 0.0.8
+ The filter property is deprecated and will be removed in a future version. Use the :func:`filter` method instead.
+
+ .. versionadded:: 0.0.3
+ """
+ super().__init__(properties)
+ self.xa_ocls=object_class
+
+ ifnotisinstance(self.xa_elem,AppKit.NSArray):
+ self.xa_elem=AppKit.NSMutableArray.alloc().initWithArray_(self.xa_elem)
+
+ iffilterisnotNone:
+ self.xa_elem=XAPredicate().from_dict(filter).evaluate(self.xa_elem)
+
+
[docs]defby_property(self,property:str,value:Any)->XAObject:
+ """Retrieves the first element whose property value matches the given value, if one exists.
+
+ :param property: The property to match
+ :type property: str
+ :param value: The value to match
+ :type value: Any
+ :return: The matching element, if one is found
+ :rtype: 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>
+
+ .. versionadded:: 0.0.6
+ """
+ predicate=XAPredicate()
+ predicate.add_eq_condition(property,value)
+ ls=predicate.evaluate(self.xa_elem)
+ ifhasattr(ls,"get"):
+ ls=predicate.evaluate(self.xa_elem).get()
+ obj=ls[0]
+ returnself._new_element(obj,self.xa_ocls)
+
+
[docs]defequalling(self,property:str,value:str)->XAObject:
+ """Retrieves all elements whose property value equals the given value.
+
+ :param property: The property to match
+ :type property: str
+ :param value: The value to search for
+ :type value: str
+ :return: The list of matching elements
+ :rtype: 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', ...]>
+
+ .. versionadded:: 0.1.0
+ """
+ predicate=XAPredicate()
+ predicate.add_eq_condition(property,value)
+ ls=predicate.evaluate(self.xa_elem)
+ returnself._new_element(ls,self.__class__)
+
+
[docs]defnot_equalling(self,property:str,value:str)->XAObject:
+ """Retrieves all elements whose property value does not equal the given value.
+
+ :param property: The property to match
+ :type property: str
+ :param value: The value to search for
+ :type value: str
+ :return: The list of matching elements
+ :rtype: 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', ...]>
+
+ .. versionadded:: 0.1.0
+ """
+ predicate=XAPredicate()
+ predicate.add_neq_condition(property,value)
+ ls=predicate.evaluate(self.xa_elem)
+ returnself._new_element(ls,self.__class__)
+
+
[docs]defcontaining(self,property:str,value:str)->XAObject:
+ """Retrieves all elements whose property value contains the given value.
+
+ :param property: The property to match
+ :type property: str
+ :param value: The value to search for
+ :type value: str
+ :return: The list of matching elements
+ :rtype: XAList
+
+ :Example:
+
+ >>> import PyXA
+ >>> app = PyXA.Application("Reminders")
+ >>> print(app.reminders().containing("name", "PyXA"))
+ <<class 'PyXA.apps.Reminders.XARemindersReminderList'>['PyXA v0.1.0 release']>
+
+ .. versionadded:: 0.0.6
+ """
+ predicate=XAPredicate()
+ predicate.add_contains_condition(property,value)
+ ls=predicate.evaluate(self.xa_elem)
+ returnself._new_element(ls,self.__class__)
+
+
[docs]defnot_containing(self,property:str,value:str)->XAObject:
+ """Retrieves all elements whose property value does not contain the given value.
+
+ :param property: The property to match
+ :type property: str
+ :param value: The value to search for
+ :type value: str
+ :return: The list of matching elements
+ :rtype: XAList
+
+ :Example:
+
+ >>> import PyXA
+ >>> app = PyXA.Application("Reminders")
+ >>> print(app.reminders().not_containing("name", " "))
+ <<class 'PyXA.apps.Reminders.XARemindersReminderList'>['Trash', 'Thing', 'Reminder', ...]>
+
+ .. versionadded:: 0.1.0
+ """
+ ls=XAPredicate.evaluate_with_format(self.xa_elem,f"NOT {property} CONTAINS \"{value}\"")
+ returnself._new_element(ls,self.__class__)
+
+
[docs]defbeginning_with(self,property:str,value:str)->XAObject:
+ """Retrieves all elements whose property value begins with the given value.
+
+ :param property: The property to match
+ :type property: str
+ :param value: The value to search for
+ :type value: str
+ :return: The list of matching elements
+ :rtype: 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', ...]>
+
+ .. versionadded:: 0.1.0
+ """
+ predicate=XAPredicate()
+ predicate.add_begins_with_condition(property,value)
+ ls=predicate.evaluate(self.xa_elem)
+ returnself._new_element(ls,self.__class__)
+
+
[docs]defending_with(self,property:str,value:str)->XAObject:
+ """Retrieves all elements whose property value ends with the given value.
+
+ :param property: The property to match
+ :type property: str
+ :param value: The value to search for
+ :type value: str
+ :return: The list of matching elements
+ :rtype: 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', ...]>
+
+ .. versionadded:: 0.1.0
+ """
+ predicate=XAPredicate()
+ predicate.add_ends_with_condition(property,value)
+ ls=predicate.evaluate(self.xa_elem)
+ returnself._new_element(ls,self.__class__)
+
+
[docs]defgreater_than(self,property:str,value:Union[int,float])->XAObject:
+ """Retrieves all elements whose property value is greater than the given value.
+
+ :param property: The property to match
+ :type property: str
+ :param value: The value to compare against
+ :type value: Union[int, float]
+ :return: The list of matching elements
+ :rtype: 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>
+
+ .. versionadded:: 0.1.0
+ """
+ predicate=XAPredicate()
+ predicate.add_gt_condition(property,value)
+ ls=predicate.evaluate(self.xa_elem)
+ returnself._new_element(ls,self.__class__)
+
+
[docs]defless_than(self,property:str,value:Union[int,float])->XAObject:
+ """Retrieves all elements whose property value is less than the given value.
+
+ :param property: The property to match
+ :type property: str
+ :param value: The value to compare against
+ :type value: Union[int, float]
+ :return: The list of matching elements
+ :rtype: 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']
+
+ .. versionadded:: 0.1.0
+ """
+ predicate=XAPredicate()
+ predicate.add_lt_condition(property,value)
+ ls=predicate.evaluate(self.xa_elem)
+ returnself._new_element(ls,self.__class__)
+
+
[docs]defbetween(self,property:str,value1:Union[int,float],value2:Union[int,float])->XAObject:
+ """Retrieves all elements whose property value is between the given values.
+
+ :param property: The property to match
+ :type property: str
+ :param value1: The lower-end of the range to match
+ :type value1: Union[int, float]
+ :param value2: The upper-end of the range to match
+ :type value2: Union[int, float]
+ :return: The list of matching elements
+ :rtype: 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']>
+
+ .. versionadded:: 0.1.0
+ """
+ predicate=XAPredicate()
+ predicate.add_gt_condition(property,value1)
+ predicate.add_lt_condition(property,value2)
+ ls=predicate.evaluate(self.xa_elem)
+ returnself._new_element(ls,self.__class__)
+
+
[docs]deffilter(self,filter:str,comparison_operation:Union[str,None]=None,value1:Union[Any,None]=None,value2:Union[Any,None]=None)->'XAList':
+ """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.
+
+ :param filter: A format string or a property name
+ :type filter: str
+ :param comparison_operation: The symbol or name of a comparison operation, such as > or <, defaults to None
+ :type comparison_operation: Union[str, None], optional
+ :param value1: The first value to compare each list item's property value against, defaults to None
+ :type value1: Union[Any, None], optional
+ :param value2: The second value to compare each list item's property value against, defaults to None
+ :type value2: Union[Any, None], optional
+ :return: The filter XAList object
+ :rtype: 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>
+
+ .. versionadded:: 0.0.8
+ """
+ ifcomparison_operationisnotNoneandvalue1isnotNone:
+ predicate=XAPredicate()
+ ifcomparison_operationin["=","==","eq","EQ","equals","EQUALS"]:
+ predicate.add_eq_condition(filter,value1)
+ elifcomparison_operationin["!=","!==","neq","NEQ","not equal to","NOT EQUAL TO"]:
+ predicate.add_neq_condition(filter,value1)
+ elifcomparison_operationin[">","gt","GT","greater than","GREATER THAN"]:
+ predicate.add_gt_condition(filter,value1)
+ elifcomparison_operationin["<","lt","LT","less than","LESS THAN"]:
+ predicate.add_lt_condition(filter,value1)
+ elifcomparison_operationin[">=","geq","GEQ","greater than or equal to","GREATER THAN OR EQUAL TO"]:
+ predicate.add_geq_condition(filter,value1)
+ elifcomparison_operationin["<=","leq","LEQ","less than or equal to","LESS THAN OR EQUAL TO"]:
+ predicate.add_leq_condition(filter,value1)
+ elifcomparison_operationin["begins with","beginswith","BEGINS WITH","BEGINSWITH"]:
+ predicate.add_begins_with_condition(filter,value1)
+ elifcomparison_operationin["contains","CONTAINS"]:
+ predicate.add_contains_condition(filter,value1)
+ elifcomparison_operationin["ends with","endswith","ENDS WITH","ENDSWITH"]:
+ predicate.add_ends_with_condition(filter,value1)
+ elifcomparison_operationin["between","BETWEEN"]:
+ predicate.add_between_condition(filter,value1,value2)
+ elifcomparison_operationin["matches","MATCHES"]:
+ predicate.add_match_condition(filter,value1)
+
+ filtered_list=predicate.evaluate(self.xa_elem)
+ returnself._new_element(filtered_list,self.__class__)
+ else:
+ filtered_list=XAPredicate.evaluate_with_format(self.xa_elem,filter)
+ returnself._new_element(filtered_list,self.__class__)
+
+
[docs]defat(self,index:int)->XAObject:
+ """Retrieves the element at the specified index.
+
+ :param index: The index of the desired element
+ :type index: int
+ :return: The PyXA-wrapped element object
+ :rtype: XAObject
+
+ .. versionadded:: 0.0.6
+ """
+ returnself._new_element(self.xa_elem[index],self.xa_ocls)
+
+ @property
+ deffirst(self)->XAObject:
+ """Retrieves the first element of the list as a wrapped PyXA object.
+
+ :return: The wrapped object
+ :rtype: XAObject
+
+ .. versionadded:: 0.0.3
+ """
+ returnself._new_element(self.xa_elem.firstObject(),self.xa_ocls)
+
+ @property
+ deflast(self)->XAObject:
+ """Retrieves the last element of the list as a wrapped PyXA object.
+
+ :return: The wrapped object
+ :rtype: XAObject
+
+ .. versionadded:: 0.0.3
+ """
+ returnself._new_element(self.xa_elem.lastObject(),self.xa_ocls)
+
+
[docs]defshuffle(self)->'XAList':
+ """Randomizes the order of objects in the list.
+
+ :return: A reference to the shuffled XAList
+ :rtype: XAList
+
+ .. versionadded:: 0.0.3
+ """
+ try:
+ self.xa_elem=self.xa_elem.shuffledArray()
+ exceptAttributeError:
+ random.shuffle(self.xa_elem)
+ returnself
+
+
[docs]defpush(self,*elements:list[XAObject]):
+ """Appends the object referenced by the provided PyXA wrapper to the end of the list.
+
+ .. versionadded:: 0.0.3
+ """
+ forelementinelements:
+ self.xa_elem.addObject_(element.xa_elem)
+
+
[docs]definsert(self,element:XAObject,index:int):
+ """Inserts the object referenced by the provided PyXA wrapper at the specified index.
+
+ .. versionadded:: 0.0.3
+ """
+ self.xa_elem.insertObject_atIndex_(element.xa_elem,index)
+
+
[docs]defpop(self,index:int=-1)->XAObject:
+ """Removes the object at the specified index from the list and returns it.
+
+ .. versionadded:: 0.0.3
+ """
+ removed=self.xa_elem.lastObject()
+ self.xa_elem.removeLastObject()
+ returnself._new_element(removed,self.xa_ocls)
[docs]deffrom_dict(self,ref_dict:dict)->'XAPredicate':
+ """Populates the XAPredicate object from the supplied dictionary.
+
+ The predicate will use == for all comparisons.
+
+ :param ref_dict: A specification of key, value pairs
+ :type ref_dict: dict
+ :return: The populated predicate object
+ :rtype: XAPredicate
+
+ .. versionadded:: 0.0.4
+ """
+ forkey,valueinref_dict.items():
+ self.keys.append(key)
+ self.operators.append("==")
+ self.values.append(value)
+ returnself
+
+
[docs]deffrom_args(self,*args)->'XAPredicate':
+ """Populates the XAPredicate object from the supplied key, value argument pairs.
+
+ The number of keys and values must be equal. The predicate will use == for all comparisons.
+
+ :raises InvalidPredicateError: Raised when the number of keys does not match the number of values
+ :return: The populated predicate object
+ :rtype: XAPredicate
+
+ .. versionadded:: 0.0.4
+ """
+ arg_num=len(args)
+ ifarg_num%2!=0:
+ raiseInvalidPredicateError("The number of keys and values must be equal; the number of arguments must be an even number.")
+
+ forindex,valueinenumerate(args):
+ ifindex%2==0:
+ self.keys.append(value)
+ self.operators.append("==")
+ self.values.append(args[index+1])
+ returnself
+
+
[docs]defevaluate(self,target:Union[AppKit.NSArray,XAList])->AppKit.NSArray:
+ """Evaluates the predicate on the given array.
+
+ :param target: The array to evaluate against the predicate
+ :type target: AppKit.NSArray
+ :return: The filtered array
+ :rtype: AppKit.NSArray
+
+ .. versionadded:: 0.0.4
+ """
+ target_list=target
+ ifisinstance(target,XAList):
+ target_list=target.xa_elem
+
+ placeholders=["%@"]*len(self.values)
+ expressions=[" ".join(expr)forexprinzip(self.keys,self.operators,placeholders)]
+ format="( "+" ) && ( ".join(expressions)+" )"
+
+ predicate=AppKit.NSPredicate.predicateWithFormat_(format,*self.values)
+ predicate=str(predicate)# Not sure why this is necessary sometimes, but it is.
+ ls=target_list.filteredArrayUsingPredicate_(AppKit.NSPredicate.predicateWithFormat_(predicate))
+
+ ifisinstance(target,XAList):
+ returntarget.__class__({
+ "parent":target,
+ "appspace":AppKit.NSApplication.sharedApplication(),
+ "workspace":AppKit.NSWorkspace.sharedWorkspace(),
+ "element":ls,
+ "appref":AppKit.NSApplication.sharedApplication(),
+ })
+ returnls
+
+
[docs]defevaluate_with_format(target:Union[AppKit.NSArray,XAList],fmt:str)->AppKit.NSArray:
+ """Evaluates the specified array against a predicate with the given format.
+
+ :param target: The array to filter
+ :type target: AppKit.NSArray
+ :param fmt: The format string for the predicate
+ :type fmt: str
+ :return: The filtered array
+ :rtype: AppKit.NSArray
+
+ .. versionadded:: 0.0.4
+ """
+ target_list=target
+ ifisinstance(target,XAList):
+ target_list=target.xa_elem
+
+ predicate=AppKit.NSPredicate.predicateWithFormat_(fmt)
+ ls=target_list.filteredArrayUsingPredicate_(predicate)
+
+ ifisinstance(target,XAList):
+ returntarget.__class__({
+ "parent":target,
+ "appspace":AppKit.NSApplication.sharedApplication(),
+ "workspace":AppKit.NSWorkspace.sharedWorkspace(),
+ "element":ls,
+ "appref":AppKit.NSApplication.sharedApplication(),
+ })
+ returnls
+
+
[docs]defevaluate_with_dict(target:Union[AppKit.NSArray,XAList],properties_dict:dict)->AppKit.NSArray:
+ """Evaluates the specified array against a predicate constructed from the supplied dictionary.
+
+ The predicate will use == for all comparisons.
+
+ :param target: The array to filter
+ :type target: AppKit.NSArray
+ :param properties_dict: The specification of key, value pairs
+ :type properties_dict: dict
+ :return: The filtered array
+ :rtype: AppKit.NSArray
+
+ .. versionadded:: 0.0.4
+ """
+ target_list=target
+ ifisinstance(target,XAList):
+ target_list=target.xa_elem
+
+ fmt=""
+ forkey,valueinproperties_dict.items():
+ ifisinstance(value,str):
+ value="'"+value+"'"
+ fmt+=f"( {key} == {value} ) &&"
+
+ predicate=AppKit.NSPredicate.predicateWithFormat_(fmt[:-3])
+ ls=target_list.filteredArrayUsingPredicate_(predicate)
+
+ ifisinstance(target,XAList):
+ returntarget.__class__({
+ "parent":target,
+ "appspace":AppKit.NSApplication.sharedApplication(),
+ "workspace":AppKit.NSWorkspace.sharedWorkspace(),
+ "element":ls,
+ "appref":AppKit.NSApplication.sharedApplication(),
+ })
+ returnls
+
+ # EQUAL
+
[docs]defadd_eq_condition(self,property:str,value:Any):
+ """Appends an `==` condition to the end of the predicate format.
+
+ The added condition will have the form `property == value`.
+
+ :param property: A property of an object to check the condition against
+ :type property: str
+ :param value: The target value of the condition
+ :type value: Any
+
+ .. versionadded:: 0.0.4
+ """
+ self.keys.append(property)
+ self.operators.append("==")
+ self.values.append(value)
+
+
[docs]definsert_eq_condition(self,index:int,property:str,value:Any):
+ """Inserts an `==` condition to the predicate format at the desired location, specified by index.
+
+ The added condition will have the form `property == value`.
+
+ :param property: A property of an object to check the condition against
+ :type property: str
+ :param value: The target value of the condition
+ :type value: Any
+
+ .. versionadded:: 0.0.4
+ """
+ self.keys.insert(index,property)
+ self.operators.insert(index,"==")
+ self.values.insert(index,value)
+
+ # NOT EQUAL
+
[docs]defadd_neq_condition(self,property:str,value:Any):
+ """Appends a `!=` condition to the end of the predicate format.
+
+ The added condition will have the form `property != value`.
+
+ :param property: A property of an object to check the condition against
+ :type property: str
+ :param value: The target value of the condition
+ :type value: Any
+
+ .. versionadded:: 0.0.4
+ """
+ self.keys.append(property)
+ self.operators.append("!=")
+ self.values.append(value)
+
+
[docs]definsert_neq_condition(self,index:int,property:str,value:Any):
+ """Inserts a `!=` condition to the predicate format at the desired location, specified by index.
+
+ The added condition will have the form `property != value`.
+
+ :param property: A property of an object to check the condition against
+ :type property: str
+ :param value: The target value of the condition
+ :type value: Any
+
+ .. versionadded:: 0.0.4
+ """
+ self.keys.insert(index,property)
+ self.operators.insert(index,"!=")
+ self.values.insert(index,value)
+
+ # GREATER THAN OR EQUAL
+
[docs]defadd_geq_condition(self,property:str,value:Any):
+ """Appends a `>=` condition to the end of the predicate format.
+
+ The added condition will have the form `property >= value`.
+
+ :param property: A property of an object to check the condition against
+ :type property: str
+ :param value: The target value of the condition
+ :type value: Any
+
+ .. versionadded:: 0.0.4
+ """
+ self.keys.append(property)
+ self.operators.append(">=")
+ self.values.append(value)
+
+
[docs]definsert_geq_condition(self,index:int,property:str,value:Any):
+ """Inserts a `>=` condition to the predicate format at the desired location, specified by index.
+
+ The added condition will have the form `property >= value`.
+
+ :param property: A property of an object to check the condition against
+ :type property: str
+ :param value: The target value of the condition
+ :type value: Any
+
+ .. versionadded:: 0.0.4
+ """
+ self.keys.insert(index,property)
+ self.operators.insert(index,">=")
+ self.values.insert(index,value)
+
+ # LESS THAN OR EQUAL
+
[docs]defadd_leq_condition(self,property:str,value:Any):
+ """Appends a `<=` condition to the end of the predicate format.
+
+ The added condition will have the form `property <= value`.
+
+ :param property: A property of an object to check the condition against
+ :type property: str
+ :param value: The target value of the condition
+ :type value: Any
+
+ .. versionadded:: 0.0.4
+ """
+ self.keys.append(property)
+ self.operators.append("<=")
+ self.values.append(value)
+
+
[docs]definsert_leq_condition(self,index:int,property:str,value:Any):
+ """Inserts a `<=` condition to the predicate format at the desired location, specified by index.
+
+ The added condition will have the form `property <= value`.
+
+ :param property: A property of an object to check the condition against
+ :type property: str
+ :param value: The target value of the condition
+ :type value: Any
+
+ .. versionadded:: 0.0.4
+ """
+ self.keys.insert(index,property)
+ self.operators.insert(index,"<=")
+ self.values.insert(index,value)
+
+ # GREATER THAN
+
[docs]defadd_gt_condition(self,property:str,value:Any):
+ """Appends a `>` condition to the end of the predicate format.
+
+ The added condition will have the form `property > value`.
+
+ :param property: A property of an object to check the condition against
+ :type property: str
+ :param value: The target value of the condition
+ :type value: Any
+
+ .. versionadded:: 0.0.4
+ """
+ self.keys.append(property)
+ self.operators.append(">")
+ self.values.append(value)
+
+
[docs]definsert_gt_condition(self,index:int,property:str,value:Any):
+ """Inserts a `>` condition to the predicate format at the desired location, specified by index.
+
+ The added condition will have the form `property > value`.
+
+ :param property: A property of an object to check the condition against
+ :type property: str
+ :param value: The target value of the condition
+ :type value: Any
+
+ .. versionadded:: 0.0.4
+ """
+ self.keys.insert(index,property)
+ self.operators.insert(index,">")
+ self.values.insert(index,value)
+
+ # LESS THAN
+
[docs]defadd_lt_condition(self,property:str,value:Any):
+ """Appends a `<` condition to the end of the predicate format.
+
+ The added condition will have the form `property < value`.
+
+ :param property: A property of an object to check the condition against
+ :type property: str
+ :param value: The target value of the condition
+ :type value: Any
+
+ .. versionadded:: 0.0.4
+ """
+ self.keys.append(property)
+ self.operators.append("<")
+ self.values.append(value)
+
+
[docs]definsert_lt_condition(self,index:int,property:str,value:Any):
+ """Inserts a `<` condition to the predicate format at the desired location, specified by index.
+
+ The added condition will have the form `property < value`.
+
+ :param property: A property of an object to check the condition against
+ :type property: str
+ :param value: The target value of the condition
+ :type value: Any
+
+ .. versionadded:: 0.0.4
+ """
+ self.keys.insert(index,property)
+ self.operators.insert(index,"<")
+ self.values.insert(index,value)
+
+ # BETWEEN
+
[docs]defadd_between_condition(self,property:str,value1:Union[int,float],value2:Union[int,float]):
+ """Appends a `BETWEEN` condition to the end of the predicate format.
+
+ The added condition will have the form `property BETWEEN [value1, value2]`.
+
+ :param property: A property of an object to check the condition against
+ :type property: str
+ :param value1: The lower target value of the condition
+ :type value1: Union[int, float]
+ :param value2: The upper target value of the condition
+ :type value2: Union[int, float]
+
+ .. versionadded:: 0.0.4
+ """
+ self.keys.append(property)
+ self.operators.append("BETWEEN")
+ self.values.append([value1,value2])
+
+
[docs]definsert_between_condition(self,index:int,property:str,value1:Union[int,float],value2:Union[int,float]):
+ """Inserts a `BETWEEN` condition to the predicate format at the desired location, specified by index.
+
+ The added condition will have the form `property BETWEEN [value1, value2]`.
+
+ :param property: A property of an object to check the condition against
+ :type property: str
+ :param value1: The lower target value of the condition
+ :type value1: Union[int, float]
+ :param value2: The upper target value of the condition
+ :type valu2e: Union[int, float]
+
+ .. versionadded:: 0.0.4
+ """
+ self.keys.insert(index,property)
+ self.operators.insert(index,"BETWEEN")
+ self.values.insert(index,[value1,value2])
+
+ # BEGINSWITH
+
[docs]defadd_begins_with_condition(self,property:str,value:Any):
+ """Appends a `BEGINSWITH` condition to the end of the predicate format.
+
+ The added condition will have the form `property BEGINSWITH value`.
+
+ :param property: A property of an object to check the condition against
+ :type property: str
+ :param value: The target value of the condition
+ :type value: Any
+
+ .. versionadded:: 0.0.4
+ """
+ self.keys.append(property)
+ self.operators.append("BEGINSWITH")
+ self.values.append(value)
+
+
[docs]definsert_begins_with_condition(self,index:int,property:str,value:Any):
+ """Inserts a `BEGINSWITH` condition to the predicate format at the desired location, specified by index.
+
+ The added condition will have the form `property BEGINSWITH value`.
+
+ :param property: A property of an object to check the condition against
+ :type property: str
+ :param value: The target value of the condition
+ :type value: Any
+
+ .. versionadded:: 0.0.4
+ """
+ self.keys.insert(index,property)
+ self.operators.insert(index,"BEGINSWITH")
+ self.values.insert(index,value)
+
+ # ENDSWITH
+
[docs]defadd_ends_with_condition(self,property:str,value:Any):
+ """Appends a `ENDSWITH` condition to the end of the predicate format.
+
+ The added condition will have the form `property ENDSWITH value`.
+
+ :param property: A property of an object to check the condition against
+ :type property: str
+ :param value: The target value of the condition
+ :type value: Any
+
+ .. versionadded:: 0.0.4
+ """
+ self.keys.append(property)
+ self.operators.append("ENDSWITH")
+ self.values.append(value)
+
+
[docs]definsert_ends_with_condition(self,index:int,property:str,value:Any):
+ """Inserts a `ENDSWITH` condition to the predicate format at the desired location, specified by index.
+
+ The added condition will have the form `property ENDSWITH value`.
+
+ :param property: A property of an object to check the condition against
+ :type property: str
+ :param value: The target value of the condition
+ :type value: Any
+
+ .. versionadded:: 0.0.4
+ """
+ self.keys.insert(index,property)
+ self.operators.insert(index,"ENDSWITH")
+ self.values.insert(index,value)
+
+ # CONTAINS
+
[docs]defadd_contains_condition(self,property:str,value:Any):
+ """Appends a `CONTAINS` condition to the end of the predicate format.
+
+ The added condition will have the form `property CONTAINS value`.
+
+ :param property: A property of an object to check the condition against
+ :type property: str
+ :param value: The target value of the condition
+ :type value: Any
+
+ .. versionadded:: 0.0.4
+ """
+ self.keys.append(property)
+ self.operators.append("CONTAINS")
+ self.values.append(value)
+
+
[docs]definsert_contains_condition(self,index:int,property:str,value:Any):
+ """Inserts a `CONTAINS` condition to the predicate format at the desired location, specified by index.
+
+ The added condition will have the form `property CONTAINS value`.
+
+ :param property: A property of an object to check the condition against
+ :type property: str
+ :param value: The target value of the condition
+ :type value: Any
+
+ .. versionadded:: 0.0.4
+ """
+ self.keys.insert(index,property)
+ self.operators.insert(index,"CONTAINS")
+ self.values.insert(index,value)
+
+ # MATCHES
+
[docs]defadd_match_condition(self,property:str,value:Any):
+ """Appends a `MATCHES` condition to the end of the predicate format.
+
+ The added condition will have the form `property MATCHES value`.
+
+ :param property: A property of an object to check the condition against
+ :type property: str
+ :param value: The target value of the condition
+ :type value: Any
+
+ .. versionadded:: 0.0.4
+ """
+ self.keys.append(property)
+ self.operators.append("MATCHES")
+ self.values.append(value)
+
+
[docs]definsert_match_condition(self,index:int,property:str,value:Any):
+ """Inserts a `MATCHES` condition to the predicate format at the desired location, specified by index.
+
+ The added condition will have the form `property MATCHES value`.
+
+ :param property: A property of an object to check the condition against
+ :type property: str
+ :param value: The target value of the condition
+ :type value: Any
+
+ .. versionadded:: 0.0.4
+ """
+ self.keys.insert(index,property)
+ self.operators.insert(index,"MATCHES")
+ self.values.insert(index,value)
+
+
[docs]defget_clipboard_representation(self)->str:
+ """Gets a clipboard-codable representation of the predicate.
+
+ When a predicate is copied to the clipboard, the string representation of the predicate is added to the clipboard.
+
+ :return: The string representation of the predicate
+ :rtype: str
+
+ .. versionadded:: 0.0.8
+ """
+ placeholders=["%@"]*len(self.values)
+ expressions=[" ".join(expr)forexprinzip(self.keys,self.operators,placeholders)]
+ format="( "+" ) && ( ".join(expressions)+" )"
+ predicate=AppKit.NSPredicate.predicateWithFormat_(format,*self.values)
+ returnpredicate.predicateFormat()
+
+
+
+
+
[docs]classXAURL(XAObject,XAClipboardCodable):
+ """A URL using any scheme recognized by the system. This can be a file URL.
+
+ .. versionadded:: 0.0.5
+ """
+ def__init__(self,url:Union[str,AppKit.NSURL]):
+ super().__init__()
+ self.parameters:str#: The query parameters of the URL
+ self.scheme:str#: The URI scheme of the URL
+ self.fragment:str#: The fragment identifier following a # symbol in the URL
+ self.port:int#: The port that the URL points to
+ self.html:element.tag#: The html of the URL
+ self.title:str#: The title of the URL
+ self.soup:BeautifulSoup=None#: The bs4 object for the URL, starts as None until a bs4-related action is made
+ self.url:str=url#: The string form of the URL
+ ifisinstance(url,str):
+ url=url.replace(" ","%20")
+ url=AppKit.NSURL.alloc().initWithString_(url)
+ self.xa_elem=url
+
+ @property
+ defbase_url(self)->str:
+ returnself.xa_elem.host()
+
+ @property
+ defparameters(self)->str:
+ returnself.xa_elem.query()
+
+ @property
+ defscheme(self)->str:
+ returnself.xa_elem.scheme()
+
+ @property
+ deffragment(self)->str:
+ returnself.xa_elem.fragment()
+
+ @property
+ defhtml(self)->element.Tag:
+ ifself.soupisNone:
+ self.__get_soup()
+ returnself.soup.html
+
+ @property
+ deftitle(self)->str:
+ ifself.soupisNone:
+ self.__get_soup()
+ returnself.soup.title.text
+
+ def__get_soup(self):
+ req=requests.get(str(self.xa_elem))
+ self.soup=BeautifulSoup(req.text,"html.parser")
+
+
[docs]defopen(self):
+ """Opens the URL in the appropriate default application.
+
+ .. versionadded:: 0.0.5
+ """
+ AppKit.NSWorkspace.sharedWorkspace().openURL_(self.xa_elem)
+
+
[docs]defextract_text(self)->list[str]:
+ """Extracts the visible text from the webpage that the URL points to.
+
+ :return: The list of extracted lines of text
+ :rtype: list[str]
+
+ .. versionadded:: 0.0.8
+ """
+ ifself.soupisNone:
+ self.__get_soup()
+ returnself.soup.get_text().splitlines()
+
+
[docs]defextract_images(self)->list['XAImage']:
+ """Extracts all images from HTML of the webpage that the URL points to.
+
+ :return: The list of extracted images
+ :rtype: list[XAImage]
+
+ .. versionadded:: 0.0.8
+ """
+ data=AppKit.NSData.alloc().initWithContentsOfURL_(AppKit.NSURL.URLWithString_(str(self.xa_elem)))
+ image=AppKit.NSImage.alloc().initWithData_(data)
+
+ ifimageisnotNone:
+ image_object=XAImage(image,name=self.xa_elem.pathComponents()[-1])
+ return[image_object]
+ else:
+ ifself.soupisNone:
+ self.__get_soup()
+
+ images=self.soup.findAll("img")
+ image_objects=[]
+ forimageinimages:
+ image_src=image["src"]
+ ifimage_src.startswith("/"):
+ image_src=str(self)+str(image["src"])
+
+ data=AppKit.NSData.alloc().initWithContentsOfURL_(AppKit.NSURL.URLWithString_(image_src))
+ image=AppKit.NSImage.alloc().initWithData_(data)
+ ifimageisnotNone:
+ image_object=XAImage(image,name=XAURL(image_src).xa_elem.pathComponents()[-1])
+ image_objects.append(image_object)
+
+ returnimage_objects
+
+
[docs]defget_clipboard_representation(self)->list[Union[AppKit.NSURL,str]]:
+ """Gets a clipboard-codable representation of the URL.
+
+ When the clipboard content is set to a URL, the raw URL data and the string representation of the URL are added to the clipboard.
+
+ :return: The clipboard-codable form of the URL
+ :rtype: Any
+
+ .. versionadded:: 0.0.8
+ """
+ return[self.xa_elem,str(self.xa_elem)]
[docs]classXAPath(XAObject,XAClipboardCodable):
+ """A path to a file on the disk.
+
+ .. versionadded:: 0.0.5
+ """
+ def__init__(self,path:Union[str,AppKit.NSURL]):
+ super().__init__()
+ ifisinstance(path,str):
+ path=AppKit.NSURL.alloc().initFileURLWithPath_(path)
+ self.xa_elem=path
+ self.path=path.path()#: The path string without the file:// prefix
+ self.xa_wksp=AppKit.NSWorkspace.sharedWorkspace()
+
+
[docs]defopen(self):
+ """Opens the file in its default application.
+
+ .. versionadded: 0.0.5
+ """
+ self.xa_wksp.openURL_(self.xa_elem)
+
+
[docs]defshow_in_finder(self):
+ """Opens a Finder window showing the folder containing this path, with the associated file selected. Synonymous with :func:`select`.
+
+ .. versionadded: 0.0.9
+ """
+ self.select()
+
+
[docs]defselect(self):
+ """Opens a Finder window showing the folder containing this path, with the associated file selected. Synonymous with :func:`show_in_finder`.
+
+ .. versionadded: 0.0.5
+ """
+ self.xa_wksp.activateFileViewerSelectingURLs_([self.xa_elem])
+
+
[docs]defget_clipboard_representation(self)->list[Union[AppKit.NSURL,str]]:
+ """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.
+
+ :return: The clipboard-codable form of the path
+ :rtype: Any
+
+ .. versionadded:: 0.0.8
+ """
+ return[self.xa_elem,self.xa_elem.path()]
[docs]classAppleScript(XAObject):
+ """A class for constructing and executing AppleScript scripts.
+
+ .. versionadded:: 0.0.5
+ """
+ def__init__(self,script:Union[str,list[str],None]=None):
+ """Creates a new AppleScript object.
+
+ :param script: A string or list of strings representing lines of AppleScript code, or the path to a script plaintext file, defaults to None
+ :type script: Union[str, list[str], None], optional
+
+ .. versionadded:: 0.0.5
+ """
+ self.script:list[str]#: The lines of AppleScript code contained in the script
+ self.last_result:Any#: The return value of the last execution of the script
+ self.file_path:XAPath#: The file path of this script, if one exists
+
+ ifisinstance(script,str):
+ ifscript.startswith("/"):
+ withopen(script,'r')asf:
+ script=f.readlines()
+ else:
+ self.script=[script]
+ elifisinstance(script,list):
+ self.script=script
+ elifscript==None:
+ self.script=[]
+
+ @property
+ deflast_result(self)->Any:
+ returnself.__last_result
+
+ @property
+ deffile_path(self)->'XAPath':
+ returnself.__file_path
+
+
[docs]defadd(self,script:Union[str,list[str],'AppleScript']):
+ """Adds the supplied string, list of strings, or script as a new line entry in the script.
+
+ :param script: The script to append to the current script string.
+ :type script: Union[str, list[str], AppleScript]
+
+ :Example:
+
+ >>> import PyXA
+ >>> script = PyXA.AppleScript("tell application \"Safari\"")
+ >>> script.add("print the document of window 1")
+ >>> script.add("end tell")
+ >>> script.run()
+
+ .. versionadded:: 0.0.5
+ """
+ ifisinstance(script,str):
+ self.script.append(script)
+ elifisinstance(script,list):
+ self.script.extend(script)
+ elifisinstance(script,AppleScript):
+ self.script.extend(script.script)
+
+
[docs]definsert(self,index:int,script:Union[str,list[str],'AppleScript']):
+ """Inserts the supplied string, list of strings, or script as a line entry in the script starting at the given line index.
+
+ :param index: The line index to begin insertion at
+ :type index: int
+ :param script: The script to insert into the current script
+ :type script: Union[str, list[str], AppleScript]
+
+ :Example:
+
+ >>> import PyXA
+ >>> script = PyXA.AppleScript.load("/Users/exampleUser/Downloads/Test.scpt")
+ >>> script.insert(1, "activate")
+ >>> script.run()
+
+ .. versionadded:: 0.0.9
+ """
+ ifisinstance(script,str):
+ self.script.insert(index,script)
+ elifisinstance(script,list):
+ forlineinscript:
+ self.script.insert(index,line)
+ index+=1
+ elifisinstance(script,AppleScript):
+ forlineinscript.script:
+ self.script.insert(index,line)
+ index+=1
+
+
[docs]defpop(self,index:int=-1)->str:
+ """Removes the line at the given index from the script.
+
+ :param index: The index of the line to remove
+ :type index: int
+ :return: The text of the removed line
+ :rtype: str
+
+ :Example:
+
+ >>> import PyXA
+ >>> script = PyXA.AppleScript.load("/Users/exampleUser/Downloads/Test.scpt")
+ >>> print(script.pop(1))
+ get chats
+
+ .. versionadded:: 0.0.9
+ """
+ returnself.script.pop(index)
[docs]classXAClipboard(XAObject):
+ """A wrapper class for managing and interacting with the system clipboard.
+
+ .. versionadded:: 0.0.5
+ """
+ def__init__(self):
+ self.xa_elem=AppKit.NSPasteboard.generalPasteboard()
+ self.content#: The content of the clipboard
+
+ @property
+ defcontent(self)->dict[str,list[Any]]:
+ info_by_type={}
+ foriteminself.xa_elem.pasteboardItems():
+ foritem_typeinitem.types():
+ info_by_type[item_type]={
+ "data":item.dataForType_(item_type),
+ "properties":item.propertyListForType_(item_type),
+ "strings":item.stringForType_(item_type),
+ }
+ returninfo_by_type
+
+ @content.setter
+ defcontent(self,value:list[Any]):
+ ifnotisinstance(value,list):
+ value=[value]
+ self.xa_elem.clearContents()
+ forindex,iteminenumerate(value):
+ ifitem==None:
+ value[index]=""
+ elifisinstance(item,XAObject):
+ ifnotisinstance(item,XAClipboardCodable):
+ print(item,"is not a clipboard-codable object.")
+ continue
+ ifisinstance(item.xa_elem,ScriptingBridge.SBElementArray)anditem.xa_elem.get()isNone:
+ value[index]=""
+ else:
+ content=item.get_clipboard_representation()
+ ifisinstance(content,list):
+ value.pop(index)
+ value+=content
+ else:
+ value[index]=content
+ elifisinstance(item,int)orisinstance(item,float):
+ value[index]=str(item)
+ self.xa_elem.writeObjects_(value)
+
+
[docs]defclear(self):
+ """Clears the system clipboard.
+
+ .. versionadded:: 0.0.5
+ """
+ self.xa_elem.clearContents()
+
+
[docs]defget_strings(self)->list[str]:
+ """Retrieves string type data from the clipboard, if any such data exists.
+
+ :return: The list of strings currently copied to the clipboard
+ :rtype: list[str]
+
+ .. versionadded:: 0.0.8
+ """
+ items=[]
+ foriteminself.xa_elem.pasteboardItems():
+ string=item.stringForType_(AppKit.NSPasteboardTypeString)
+ ifstringisnotNone:
+ items.append(string)
+ returnitems
+
+
[docs]defget_urls(self)->list['XAURL']:
+ """Retrieves URL type data from the clipboard, as instances of :class:`XAURL` and :class:`XAPath`, if any such data exists.
+
+ :return: The list of file URLs and web URLs currently copied to the clipboard
+ :rtype: list[XAURL]
+
+ .. versionadded:: 0.0.8
+ """
+ items=[]
+ foriteminself.xa_elem.pasteboardItems():
+ url=None
+ string=item.stringForType_(AppKit.NSPasteboardTypeURL)
+ ifstringisNone:
+ string=item.stringForType_(AppKit.NSPasteboardTypeFileURL)
+ ifstringisnotNone:
+ url=XAPath(XAURL(string).xa_elem)
+ else:
+ url=XAURL(string)
+
+ ifurlisnotNone:
+ items.append(url)
+ returnitems
+
+
[docs]defget_images(self)->list['XAImage']:
+ """Retrieves image type data from the clipboard, as instances of :class:`XAImage`, if any such data exists.
+
+ :return: The list of images currently copied to the clipboard
+ :rtype: list[XAImage]
+
+ .. versionadded:: 0.0.8
+ """
+ image_types=[AppKit.NSPasteboardTypePNG,AppKit.NSPasteboardTypeTIFF,'public.jpeg','com.apple.icns']
+ items=[]
+ foriteminself.xa_elem.pasteboardItems():
+ forimage_typeinimage_types:
+ ifimage_typeinitem.types():
+ img=XAImage(data=item.dataForType_(image_type))
+ items.append(img)
+ returnitems
+
+
[docs]defset_contents(self,content:list[Any]):
+ """Sets the content of the clipboard
+
+ :param content: A list of the content to add fill the clipboard with.
+ :type content: list[Any]
+
+ .. deprecated:: 0.0.8
+ Set the :ivar:`content` property directly instead.
+
+ .. versionadded:: 0.0.5
+ """
+ self.xa_elem.clearContents()
+ self.xa_elem.writeObjects_(content)
+
+
+
+
+
[docs]classXANotification(XAObject):
+ """A class for managing and interacting with notifications.
+
+ .. versionadded:: 0.0.9
+ """
+ def__init__(self,text:str,title:Union[str,None]=None,subtitle:Union[str,None]=None,sound_name:Union[str,None]=None):
+ """Initializes a notification object.
+
+ :param text: The main text of the notification
+ :type text: str
+ :param title: The title of the notification, defaults to None
+ :type title: Union[str, None], optional
+ :param subtitle: The subtitle of the notification, defaults to None
+ :type subtitle: Union[str, None], optional
+ :param sound_name: The sound to play when the notification is displayed, defaults to None
+ :type sound_name: Union[str, None], optional
+
+ .. versionadded:: 0.0.9
+ """
+ self.text=text
+ self.title=title
+ self.subtitle=subtitle
+ self.sound_name=sound_name
+
+
[docs]defdisplay(self):
+ """Displays the notification.
+
+ .. todo::
+
+ Currently uses :func:`subprocess.Popen`. Should use UserNotifications in the future.
+
+ .. versionadded:: 0.0.9
+ """
+ script=AppleScript()
+ script.add(f"display notification \\\"{self.text}\\\"")
+
+ ifself.titleisnotNone:
+ script.add(f"with title \\\"{self.title}\\\"")
+
+ ifself.subtitleisnotNone:
+ script.add(f"subtitle \\\"{self.subtitle}\\\"")
+
+ ifself.sound_nameisnotNone:
+ script.add(f"sound name \\\"{self.sound_name}\\\"")
+
+ cmd="osascript -e \""+" ".join(script.script)+"\""
+ subprocess.Popen([cmd],shell=True)
+
+
+
+
+
[docs]classXAProcess(XAObject):
+ def__init__(self,properties):
+ super().__init__(properties)
+ self.xa_wcls=properties["window_class"]
+ self.id=self.xa_elem.id()
+ self.unix_id=self.xa_elem.unixId()
+
+ self.front_window:XAWindow#: The front window of the application process
+
+ @property
+ deffront_window(self)->'XAWindow':
+ returnself._new_element(self.xa_elem.windows()[0],XAWindow)
+
+
[docs]classXACommandDetector(XAObject):
+ """A command-based query detector.
+
+ .. versionadded:: 0.0.9
+ """
+ def__init__(self,command_function_map:Union[dict[str,Callable[[],Any]],None]=None):
+ """Creates a command detector object.
+
+ :param command_function_map: A dictionary mapping command strings to function objects
+ :type command_function_map: dict[str, Callable[[], Any]]
+
+ .. versionadded:: 0.0.9
+ """
+ self.command_function_map=command_function_mapor{}#: The dictionary of commands and corresponding functions to run upon detection
+
+
[docs]defon_detect(self,command:str,function:Callable[[],Any]):
+ """Adds or replaces a command to listen for upon calling :func:`listen`, and associates the given function with that command.
+
+ :param command: The command to listen for
+ :type command: str
+ :param function: The function to call when the command is heard
+ :type function: Callable[[], Any]
+
+ :Example:
+
+ >>> detector = PyXA.XACommandDetector()
+ >>> detector.on_detect("go to google", PyXA.XAURL("http://google.com").open)
+ >>> detector.listen()
+
+ .. versionadded:: 0.0.9
+ """
+ self.command_function_map[command]=function
[docs]classXASpeechRecognizer(XAObject):
+ """A rule-based query detector.
+
+ .. versionadded:: 0.0.9
+ """
+ def__init__(self,finish_conditions:Union[None,dict[Callable[[str],bool],Callable[[str],bool]]]=None):
+ """Creates a speech recognizer object.
+
+ By default, with no other rules specified, the Speech Recognizer will timeout after 10 seconds once :func:`listen` is called.
+
+ :param finish_conditions: A dictionary of rules and associated methods to call when a rule evaluates to true, defaults to None
+ :type finish_conditions: Union[None, dict[Callable[[str], bool], Callable[[str], bool]]], optional
+
+ .. versionadded:: 0.0.9
+ """
+ default_conditions={
+ lambdax:self.time_elapsed>timedelta(seconds=10):lambdax:self.spoken_query,
+ }
+ self.finish_conditions:Callable[[str],bool]=finish_conditionsordefault_conditions#: A dictionary of rules and associated methods to call when a rule evaluates to true
+ self.spoken_query:str=""#: The recognized spoken input
+ self.start_time:datetime#: The time that the Speech Recognizer begins listening
+ self.time_elapsed:timedelta#: The amount of time passed since the start time
+
+ def__prepare(self):
+ # Request microphone access if we don't already have it
+ Speech.SFSpeechRecognizer.requestAuthorization_(None)
+
+ # Set up audio session
+ self.audio_session=AVFoundation.AVAudioSession.sharedInstance()
+ self.audio_session.setCategory_mode_options_error_(AVFoundation.AVAudioSessionCategoryRecord,AVFoundation.AVAudioSessionModeMeasurement,AVFoundation.AVAudioSessionCategoryOptionDuckOthers,None)
+ self.audio_session.setActive_withOptions_error_(True,AVFoundation.AVAudioSessionSetActiveOptionNotifyOthersOnDeactivation,None)
+
+ # Set up recognition request
+ self.recognizer=Speech.SFSpeechRecognizer.alloc().init()
+ self.recognition_request=Speech.SFSpeechAudioBufferRecognitionRequest.alloc().init()
+ self.recognition_request.setShouldReportPartialResults_(True)
+
+ # Set up audio engine
+ self.audio_engine=AVFoundation.AVAudioEngine.alloc().init()
+ self.input_node=self.audio_engine.inputNode()
+ recording_format=self.input_node.outputFormatForBus_(0)
+ self.input_node.installTapOnBus_bufferSize_format_block_(0,1024,recording_format,
+ lambdabuffer,_when:self.recognition_request.appendAudioPCMBuffer_(buffer))
+ self.audio_engine.prepare()
+ self.audio_engine.startAndReturnError_(None)
+
+
[docs]defon_detect(self,rule:Callable[[str],bool],method:Callable[[str],bool]):
+ """Sets the given rule to call the specified method if a spoken query passes the rule.
+
+ :param rule: A function that takes the spoken query as a parameter and returns a boolean value depending on whether the query passes a desired rule
+ :type rule: Callable[[str], bool]
+ :param method: A function that takes the spoken query as a parameter and acts on it
+ :type method: Callable[[str], bool]
+
+ .. versionadded:: 0.0.9
+ """
+ self.finish_conditions[rule]=method
+
+
[docs]deflisten(self)->Any:
+ """Begins listening for a query until a rule returns True.
+
+ :return: The value returned by the method invoked upon matching some rule
+ :rtype: Any
+
+ .. versionadded:: 0.0.9
+ """
+ self.start_time=datetime.now()
+ self.time_elapsed=None
+ self.__prepare()
+
+ old_self=self
+ defdetect_speech(transcription,error):
+ iferrorisnotNone:
+ print("Failed to detect speech. Error: ",error)
+ else:
+ old_self.spoken_query=transcription.bestTranscription().formattedString()
+ print(old_self.spoken_query)
+
+ recognition_task=self.recognizer.recognitionTaskWithRequest_resultHandler_(self.recognition_request,detect_speech)
+ whileself.spoken_query==""ornotany(x(self.spoken_query)forxinself.finish_conditions):
+ self.time_elapsed=datetime.now()-self.start_time
+ AppKit.NSRunLoop.currentRunLoop().runUntilDate_(datetime.now()+timedelta(seconds=0.5))
+
+ self.audio_engine.stop()
+ forrule,methodinself.finish_conditions.items():
+ ifrule(self.spoken_query):
+ returnmethod(self.spoken_query)
+
+
+
+
+
[docs]classXASpeech(XAObject):
+ def__init__(self,message:str="",voice:Union[str,None]=None,volume:float=0.5,rate:int=200):
+ self.message:str=message#: The message to speak
+ self.voice:Union[str,None]=voice#: The voice that the message is spoken in
+ self.volume:float=volume#: The speaking volume
+ self.rate:int=rate#: The speaking rate
+
+
[docs]defvoices(self)->list[str]:
+ """Gets the list of voice names available on the system.
+
+ :return: The list of voice names
+ :rtype: list[str]
+
+ :Example:
+
+ >>> import PyXA
+ >>> speaker = PyXA.XASpeech()
+ >>> print(speaker.voices())
+ ['Agnes', 'Alex', 'Alice', 'Allison',
+
+ .. versionadded:: 0.0.9
+ """
+ ls=AppKit.NSSpeechSynthesizer.availableVoices()
+ return[x.replace("com.apple.speech.synthesis.voice.","").replace(".premium","").title()forxinls]
+
+
[docs]defspeak(self,path:Union[str,XAPath,None]=None):
+ """Speaks the provided message using the desired voice, volume, and speaking rate.
+
+ :param path: The path to a .AIFF file to output sound to, defaults to None
+ :type path: Union[str, XAPath, None], optional
+
+ :Example 1: Speak a message aloud
+
+ >>> import PyXA
+ >>> PyXA.XASpeech("This is a test").speak()
+
+ :Example 2: Output spoken message to an AIFF file
+
+ >>> import PyXA
+ >>> speaker = PyXA.XASpeech("Hello, world!")
+ >>> speaker.speak("/Users/steven/Downloads/Hello.AIFF")
+
+ :Example 3: Control the voice, volume, and speaking rate
+
+ >>> import PyXA
+ >>> speaker = PyXA.XASpeech(
+ >>> message = "Hello, world!",
+ >>> voice = "Alex",
+ >>> volume = 1,
+ >>> rate = 500
+ >>> )
+ >>> speaker.speak()
+
+ .. versionadded:: 0.0.9
+ """
+ # Get the selected voice by name
+ voice=None
+ forvinAppKit.NSSpeechSynthesizer.availableVoices():
+ ifself.voice.lower()inv.lower():
+ voice=v
+
+ # Set up speech synthesis object
+ synthesizer=AppKit.NSSpeechSynthesizer.alloc().initWithVoice_(voice)
+ synthesizer.setVolume_(self.volume)
+ synthesizer.setRate_(self.rate)
+
+ # Start speaking
+ ifpathisNone:
+ synthesizer.startSpeakingString_(self.message)
+ else:
+ ifisinstance(path,str):
+ path=XAPath(path)
+ synthesizer.startSpeakingString_toURL_(self.message,path.xa_elem)
+
+ # Wait for speech to complete
+ whilesynthesizer.isSpeaking():
+ time.sleep(0.01)
+
+
+
+
+
[docs]classXASpotlight(XAObject):
+ """A Spotlight query for files on the disk.
+
+ .. versionadded:: 0.0.9
+ """
+ def__init__(self,*query:list[Any]):
+ self.query:list[Any]=query#: The query terms to search
+ self.timeout:int=10#: The amount of time in seconds to timeout the search after
+ self.predicate:Union[str,XAPredicate]=None#: The predicate to filter search results by
+ self.results:list[XAPath]#: The results of the search
+ self.__results=None
+
+ self.query_object=AppKit.NSMetadataQuery.alloc().init()
+ nc=AppKit.NSNotificationCenter.defaultCenter()
+ nc.addObserver_selector_name_object_(self,'_queryNotification:',None,self.query_object)
+
+ @property
+ defresults(self)->list['XAPath']:
+ iflen(self.query)==0andself.predicateisNone:
+ return[]
+ self.run()
+ total_time=0
+ whileself.__resultsisNoneandtotal_time<self.timeout:
+ AppKit.NSRunLoop.currentRunLoop().runUntilDate_(datetime.now()+timedelta(seconds=0.01))
+ total_time+=0.01
+ ifself.__resultsisNone:
+ return[]
+ returnself.__results
+
+
[docs]defrun(self):
+ """Runs the search.
+
+ :Example:
+
+ >>> import PyXA
+ >>> from datetime import date, datetime, time
+ >>> date1 = datetime.combine(date(2022, 5, 17), time(0, 0, 0))
+ >>> date2 = datetime.combine(date(2022, 5, 18), time(0, 0, 0))
+ >>> search = PyXA.XASpotlight(date1, date2)
+ >>> print(search.results)
+ [<<class 'PyXA.XAPath'>file:///Users/exampleUser/Downloads/>, <<class 'PyXA.XAPath'>file:///Users/exampleUser/Downloads/Example.txt>, ...]
+
+ .. versionadded:: 0.0.9
+ """
+ ifself.predicateisnotNone:
+ # Search with custom predicate
+ ifisinstance(self.predicate,XAPredicate):
+ self.predicate=self.predicate.get_clipboard_representation()
+ self.__search_with_predicate(self.predicate)
+ eliflen(self.query)==1andisinstance(self.query[0],datetime):
+ # Search date + or - 24 hours
+ self.__search_by_date(self.query)
+ eliflen(self.query)==2andisinstance(self.query[0],datetime)andisinstance(self.query[1],datetime):
+ # Search date range
+ self.__search_by_date_range(self.query[0],self.query[1])
+ elifall(isinstance(x,str)orisinstance(x,int)orisinstance(x,float)forxinself.query):
+ # Search matching multiple strings
+ self.__search_by_strs(self.query)
+ elifisinstance(self.query[0],datetime)andall(isinstance(x,str)orisinstance(x,int)orisinstance(x,float)forxinself.query[1:]):
+ # Search by date and string
+ self.__search_by_date_strings(self.query[0],self.query[1:])
+ elifisinstance(self.query[0],datetime)andisinstance(self.query[1],datetime)andall(isinstance(x,str)orisinstance(x,int)orisinstance(x,float)forxinself.query[2:]):
+ # Search by date range and string
+ self.__search_by_date_range_strings(self.query[0],self.query[1],self.query[2:])
+
+ AppKit.NSRunLoop.currentRunLoop().runUntilDate_(datetime.now()+timedelta(seconds=0.01))
+
+
[docs]defshow_in_finder(self):
+ """Shows the search in Finder. This might not reveal the same search results.
+
+ .. versionadded:: 0.0.9
+ """
+ AppKit.NSWorkspace.sharedWorkspace().showSearchResultsForQueryString_(str(self.query))
+
+ def__search_by_strs(self,terms:tuple[str]):
+ expanded_terms=[[x]*3forxinterms]
+ expanded_terms=[xforsublistinexpanded_termsforxinsublist]
+ format="((kMDItemDisplayName CONTAINS %@) OR (kMDItemTextContent CONTAINS %@) OR (kMDItemFSName CONTAINS %@)) AND "*len(terms)
+ self.__search_with_predicate(format[:-5],*expanded_terms)
+
+ def__search_by_date(self,date:datetime):
+ self.__search_with_predicate(f"((kMDItemContentCreationDate > %@) AND (kMDItemContentCreationDate < %@)) OR ((kMDItemContentModificationDate > %@) AND (kMDItemContentModificationDate < %@)) OR ((kMDItemFSCreationDate > %@) AND (kMDItemFSCreationDate < %@)) OR ((kMDItemFSContentChangeDate > %@) AND (kMDItemFSContentChangeDate < %@)) OR ((kMDItemDateAdded > %@) AND (kMDItemDateAdded < %@))",*[date-timedelta(hours=12),date+timedelta(hours=12)]*5)
+
+ def__search_by_date_range(self,date1:datetime,date2:datetime):
+ self.__search_with_predicate(f"((kMDItemContentCreationDate > %@) AND (kMDItemContentCreationDate < %@)) OR ((kMDItemContentModificationDate > %@) AND (kMDItemContentModificationDate < %@)) OR ((kMDItemFSCreationDate > %@) AND (kMDItemFSCreationDate < %@)) OR ((kMDItemFSContentChangeDate > %@) AND (kMDItemFSContentChangeDate < %@)) OR ((kMDItemDateAdded > %@) AND (kMDItemDateAdded < %@))",*[date1,date2]*5)
+
+ def__search_by_date_strings(self,date:datetime,terms:tuple[str]):
+ expanded_terms=[[x]*3forxinterms]
+ expanded_terms=[xforsublistinexpanded_termsforxinsublist]
+ format="((kMDItemDisplayName CONTAINS %@) OR (kMDItemTextContent CONTAINS %@) OR (kMDItemFSName CONTAINS %@)) AND "*len(terms)
+ format+="(((kMDItemContentCreationDate > %@) AND (kMDItemContentCreationDate < %@)) OR ((kMDItemContentModificationDate > %@) AND (kMDItemContentModificationDate < %@)) OR ((kMDItemFSCreationDate > %@) AND (kMDItemFSCreationDate < %@)) OR ((kMDItemFSContentChangeDate > %@) AND (kMDItemFSContentChangeDate < %@)) OR ((kMDItemDateAdded > %@) AND (kMDItemDateAdded < %@)))"
+ self.__search_with_predicate(format,*expanded_terms,*[date-timedelta(hours=12),date+timedelta(hours=12)]*5)
+
+ def__search_by_date_range_strings(self,date1:datetime,date2:datetime,terms:tuple[str]):
+ expanded_terms=[[x]*3forxinterms]
+ expanded_terms=[xforsublistinexpanded_termsforxinsublist]
+ format="((kMDItemDisplayName CONTAINS %@) OR (kMDItemTextContent CONTAINS %@) OR (kMDItemFSName CONTAINS %@)) AND "*len(terms)
+ format+="(((kMDItemContentCreationDate > %@) AND (kMDItemContentCreationDate < %@)) OR ((kMDItemContentModificationDate > %@) AND (kMDItemContentModificationDate < %@)) OR ((kMDItemFSCreationDate > %@) AND (kMDItemFSCreationDate < %@)) OR ((kMDItemFSContentChangeDate > %@) AND (kMDItemFSContentChangeDate < %@)) OR ((kMDItemDateAdded > %@) AND (kMDItemDateAdded < %@)))"
+ self.__search_with_predicate(format,*expanded_terms,*[date1,date2]*5)
+
+ def__search_with_predicate(self,predicate_format:str,*args:list[Any]):
+ predicate=AppKit.NSPredicate.predicateWithFormat_(predicate_format,*args)
+ self.query_object.setPredicate_(predicate)
+ self.query_object.startQuery()
+
+ def_queryNotification_(self,notification):
+ ifnotification.name()==AppKit.NSMetadataQueryDidFinishGatheringNotification:
+ self.query_object.stopQuery()
+ results=notification.object().results()
+ self.__results=[XAPath(x.valueForAttribute_(AppKit.NSMetadataItemPathKey))forxinresults]
[docs]classXAUIElementList(XAList):
+ """A wrapper around a list of UI elements.
+
+ All properties of UI elements can be accessed via methods on this list, returning a list of the method's return value for each element in the list.
+
+ .. versionadded:: 0.0.5
+ """
+ def__init__(self,properties:dict,filter:Union[dict,None]=None,obj_type=None):
+ ifobj_typeisNone:
+ obj_type=XAUIElement
+ super().__init__(properties,obj_type,filter)
+
+
[docs]classXAUIElement(XAObject):
+ def__init__(self,properties):
+ super().__init__(properties)
+
+ self.properties:dict#: All properties of the UI element
+ self.accessibility_description:str#: The accessibility description of the element
+ self.enabled:bool#: Whether the UI element is currently enabled
+ self.entire_contents:Any#: The entire contents of the element
+ self.focused:bool#: Whether the window is the currently element
+ self.name:str#: The name of the element
+ self.title:str#: The title of the element (often the same as its name)
+ self.position:tuple[int,int]#: The position of the top left corner of the element
+ self.size:tuple[int,int]#: The width and height of the element, in pixels
+ self.maximum_value:Any#: The maximum value that the element can have
+ self.minimum_value:Any#: The minimum value that the element can have
+ self.value:Any#: The current value of the element
+ self.role:str#: The element's role
+ self.role_description:str#: The description of the element's role
+ self.subrole:str#: The subrole of the UI element
+ self.selected:bool#: Whether the element is currently selected
+
+ @property
+ defproperties(self)->dict:
+ returnself.xa_elem.properties()
+
+ @property
+ defaccessibility_description(self)->str:
+ returnself.xa_elem.accessibilityDescription()
+
+ @property
+ defenabled(self)->bool:
+ returnself.xa_elem.enabled()
+
+ @property
+ defentire_contents(self)->list[XAObject]:
+ ls=self.xa_elem.entireContents()
+ return[self._new_element(x,XAUIElement)forxinls]
+
+ @property
+ deffocused(self)->bool:
+ returnself.xa_elem.focused()
+
+ @property
+ defname(self)->str:
+ returnself.xa_elem.name()
+
+ @property
+ deftitle(self)->str:
+ returnself.xa_elem.title()
+
+ @property
+ defposition(self)->tuple[int,int]:
+ returnself.xa_elem.position()
+
+ @property
+ defsize(self)->tuple[int,int]:
+ returnself.xa_elem.size()
+
+ @property
+ defmaximum_value(self)->Any:
+ returnself.xa_elem.maximumValue()
+
+ @property
+ defminimum_value(self)->Any:
+ returnself.xa_elem.minimumValue()
+
+ @property
+ defvalue(self)->Any:
+ returnself.xa_elem.value()
+
+ @property
+ defrole(self)->str:
+ returnself.xa_elem.role()
+
+ @property
+ defrole_description(self)->str:
+ returnself.xa_elem.roleDescription()
+
+ @property
+ defsubrole(self)->str:
+ returnself.xa_elem.subrole()
+
+ @property
+ defselected(self)->bool:
+ returnself.xa_elem.selected()
+
+
[docs]classXAWindow(XAUIElement):
+ """A general window class for windows of both officially scriptable and non-scriptable applications.
+
+ .. versionadded:: 0.0.1
+ """
+ def__init__(self,properties):
+ super().__init__(properties)
+
+
[docs]classXAUIMenuBarList(XAUIElementList):
+ """A wrapper around a list of menu bars.
+
+ .. versionadded:: 0.0.5
+ """
+ def__init__(self,properties:dict,filter:Union[dict,None]=None):
+ super().__init__(properties,filter,XAUIMenuBar)
[docs]classXAUIMenuBarItemList(XAUIElementList):
+ """A wrapper around a list of menu bar items.
+
+ .. versionadded:: 0.0.5
+ """
+ def__init__(self,properties:dict,filter:Union[dict,None]=None):
+ super().__init__(properties,filter,XAUIMenuBarItem)
[docs]classXAUIMenuList(XAUIElementList):
+ """A wrapper around a list of menus.
+
+ .. versionadded:: 0.0.5
+ """
+ def__init__(self,properties:dict,filter:Union[dict,None]=None):
+ super().__init__(properties,filter,XAUIMenu)
[docs]classXAUIMenuItemList(XAUIElementList):
+ """A wrapper around a list of menu items.
+
+ .. versionadded:: 0.0.5
+ """
+ def__init__(self,properties:dict,filter:Union[dict,None]=None):
+ super().__init__(properties,filter,XAUIMenuItem)
[docs]defclick(self)->'XAUIMenuItem':
+ """Clicks the menu item. Synonymous with :func:`press`.
+
+ :return: The menu item object.
+ :rtype: XAUIMenuItem
+
+ .. versionadded:: 0.0.2
+ """
+ self.actions({"name":"AXPress"})[0].perform()
+ returnself
+
+
[docs]defpress(self)->'XAUIMenuItem':
+ """Clicks the menu item. Synonymous with :func:`click`.
+
+ :return: The menu item object.
+ :rtype: XAUIMenuItem
+
+ .. versionadded:: 0.0.2
+ """
+ self.actions({"name":"AXPress"})[0].perform()
+ returnself
+
+
+
+
+
[docs]classXAUISplitterList(XAUIElementList):
+ """A wrapper around a list of splitters.
+
+ .. versionadded:: 0.0.8
+ """
+ def__init__(self,properties:dict,filter:Union[dict,None]=None):
+ super().__init__(properties,filter,XAUISplitter)
[docs]classXAUIToolbarList(XAUIElementList):
+ """A wrapper around a list of toolbars.
+
+ .. versionadded:: 0.0.5
+ """
+ def__init__(self,properties:dict,filter:Union[dict,None]=None):
+ super().__init__(properties,filter,XAUIToolbar)
[docs]classXAUIGroupList(XAUIElementList):
+ """A wrapper around a list of UI element groups.
+
+ .. versionadded:: 0.0.5
+ """
+ def__init__(self,properties:dict,filter:Union[dict,None]=None):
+ super().__init__(properties,filter,XAUIGroup)
+
+
[docs]classXAUIGroup(XAUIElement):
+ """A group of UI element.
+
+ .. versionadded:: 0.0.2
+ """
+ def__init__(self,properties):
+ super().__init__(properties)
+
+
+
+
+
[docs]classXAUITabGroupList(XAUIElementList):
+ """A wrapper around a list of UI element tab groups.
+
+ .. versionadded:: 0.0.5
+ """
+ def__init__(self,properties:dict,filter:Union[dict,None]=None):
+ super().__init__(properties,filter,XAUITabGroup)
[docs]defshow_menu(self)->'XAButton':
+ """Right clicks the button, invoking a menu.
+
+ :return: The button object
+ :rtype: XAButton
+
+ .. versionadded:: 0.0.2
+ """
+ self.actions({"name":"AXShowMenu"})[0].perform()
+ returnself
+
+
+
+
+
[docs]classXAUIRadioButtonList(XAUIElementList):
+ """A wrapper around lists of radio buttons that employs fast enumeration techniques.
+
+ .. versionadded:: 0.0.4
+ """
+ def__init__(self,properties:dict,filter:Union[dict,None]=None):
+ super().__init__(properties,filter,XAUIRadioButton)
[docs]classXAUIActionList(XAUIElementList):
+ """A wrapper around a list of UI element actions.
+
+ .. versionadded:: 0.0.5
+ """
+ def__init__(self,properties:dict,filter:Union[dict,None]=None):
+ super().__init__(properties,filter,XAUIAction)
[docs]classXAUITextfieldList(XAUIElementList):
+ """A wrapper around a list of textfields.
+
+ .. versionadded:: 0.0.5
+ """
+ def__init__(self,properties:dict,filter:Union[dict,None]=None):
+ super().__init__(properties,filter,XAUITextfield)
[docs]classXAUIStaticTextList(XAUIElementList):
+ """A wrapper around a list of static text elements.
+
+ .. versionadded:: 0.0.5
+ """
+ def__init__(self,properties:dict,filter:Union[dict,None]=None):
+ super().__init__(properties,filter,XAUIStaticText)
[docs]classXATextDocumentList(XAList,XAClipboardCodable):
+ """A wrapper around lists of text documents that employs fast enumeration techniques.
+
+ .. versionadded:: 0.1.0
+ """
+ def__init__(self,properties:dict,filter:Union[dict,None]=None,obj_class=None):
+ ifobj_classisNone:
+ obj_class=XATextDocument
+ super().__init__(properties,obj_class,filter)
+
+
[docs]defproperties(self)->list[dict]:
+ """Gets the properties of each document in the list.
+
+ :return: A list of document properties dictionaries
+ :rtype: list[dict]
+
+ .. versionadded:: 0.0.3
+ """
+ ls=self.xa_elem.arrayByApplyingSelector_("properties")
+ return[dict(x)forxinls]
+
+
[docs]deftext(self)->'XATextList':
+ """Gets the text of each document in the list.
+
+ :return: A list of document texts
+ :rtype: XATextList
+
+ .. versionadded:: 0.1.0
+ """
+ ls=self.xa_elem.arrayByApplyingSelector_("text")
+ returnself._new_element(ls,XATextList)
+
+
[docs]defby_properties(self,properties:dict)->Union['XATextDocument',None]:
+ """Retrieves the document whose properties match the given properties dictionary, if one exists.
+
+ :return: The desired document, if it is found
+ :rtype: Union[XATextDocument, None]
+
+ .. versionadded:: 0.1.0
+ """
+ returnself.by_property("properties",properties)
+
+
[docs]defby_text(self,text:str)->Union['XATextDocument',None]:
+ """Retrieves the first documents whose text matches the given text.
+
+ :return: The desired document, if it is found
+ :rtype: Union[XATextDocument, None]
+
+ .. versionadded:: 0.1.0
+ """
+ returnself.by_property("text",text)
+
+
[docs]defparagraphs(self)->'XAParagraphList':
+ """Gets the paragraphs of each document in the list.
+
+ :return: A combined list of all paragraphs in each document of the list
+ :rtype: XAParagraphList
+
+ .. versionadded:: 0.0.3
+ """
+ ls=self.xa_elem.arrayByApplyingSelector_("paragraphs")
+ returnself._new_element([plistforplistinls],XAParagraphList)
+
+
[docs]defwords(self)->'XAWordList':
+ """Gets the words of each document in the list.
+
+ :return: A combined list of all words in each document of the list
+ :rtype: XAWordList
+
+ .. versionadded:: 0.0.3
+ """
+ ls=self.xa_elem.arrayByApplyingSelector_("words")
+ return[self._new_element([plistforplistinls],XAWordList)]
+
+
[docs]defcharacters(self)->'XACharacterList':
+ """Gets the characters of each document in the list.
+
+ :return: A combined list of all characters in each document of the list
+ :rtype: XACharacterList
+
+ .. versionadded:: 0.0.3
+ """
+ ls=self.xa_elem.arrayByApplyingSelector_("characters")
+ return[self._new_element([plistforplistinls],XACharacterList)]
+
+
[docs]defattribute_runs(self)->'XAAttributeRunList':
+ """Gets the attribute runs of each document in the list.
+
+ :return: A combined list of all attribute runs in each document of the list
+ :rtype: XAAttributeRunList
+
+ .. versionadded:: 0.0.3
+ """
+ ls=self.xa_elem.arrayByApplyingSelector_("attributeRuns")
+ return[self._new_element([plistforplistinls],XAAttributeRunList)]
+
+
[docs]defattachments(self)->'XAAttachmentList':
+ """Gets the attachments of each document in the list.
+
+ :return: A combined list of all attachments in each document of the list
+ :rtype: XAAttachmentList
+
+ .. versionadded:: 0.0.3
+ """
+ ls=self.xa_elem.arrayByApplyingSelector_("attachments")
+ return[self._new_element([plistforplistinls],XAAttachmentList)]
+
+
[docs]defget_clipboard_representation(self)->list[Union[str,AppKit.NSURL]]:
+ """Gets a clipboard-codable representation of each document in the list.
+
+ When the clipboard content is set to a list of documents, each documents's file URL and name are added to the clipboard.
+
+ :return: A list of each document's file URL and name
+ :rtype: list[Union[str, AppKit.NSURL]]
+
+ .. versionadded:: 0.0.8
+ """
+ return[str(x)forxinself.text()]
[docs]classXATextDocument(XAObject):
+ """A class for managing and interacting with text documents.
+
+ .. versionadded:: 0.0.1
+ """
+ def__init__(self,properties):
+ super().__init__(properties)
+ self.text:XAText#: The text of the document.
+
+ @property
+ deftext(self)->'XAText':
+ returnself._new_element(self.xa_elem.text(),XAText)
+
+ @text.setter
+ deftext(self,text:str):
+ self.set_property("text",text)
+
+
[docs]defset_text(self,new_text:str)->'XATextDocument':
+ """Sets the text of the document.
+
+ :param new_text: The new text of the document
+ :type new_text: str
+ :return: A reference to the document object.
+ :rtype: XATextDocument
+
+ .. seealso:: :func:`prepend`, :func:`append`
+
+ .. deprecated:: 0.1.0
+ Directly set the text attribute instead.
+
+ .. versionadded:: 0.0.1
+ """
+ self.set_property("text",new_text)
+ returnself
+
+
[docs]defprepend(self,text:str)->'XATextDocument':
+ """Inserts the provided text at the beginning of the document.
+
+ :param text: The text to insert.
+ :type text: str
+ :return: A reference to the document object.
+ :rtype: XATextDocument
+
+ .. seealso:: :func:`append`, :func:`set_text`
+
+ .. versionadded:: 0.0.1
+ """
+ old_text=self.text
+ self.set_property("text",text+old_text)
+ returnself
+
+
[docs]defappend(self,text:str)->'XATextDocument':
+ """Appends the provided text to the end of the document.
+
+ :param text: The text to append.
+ :type text: str
+ :return: A reference to the document object.
+ :rtype: XATextDocument
+
+ .. seealso:: :func:`prepend`, :func:`set_text`
+
+ .. versionadded:: 0.0.1
+ """
+ old_text=self.text
+ self.set_property("text",old_text+text)
+ returnself
+
+
[docs]defreverse(self)->'XATextDocument':
+ """Reverses the text of the document.
+
+ :return: A reference to the document object.
+ :rtype: XATextDocument
+
+ .. versionadded:: 0.0.4
+ """
+ self.set_property("text",reversed(self.text))
+ returnself
[docs]classXATextList(XAList):
+ """A wrapper around lists of text objects that employs fast enumeration techniques.
+
+ .. versionadded:: 0.0.4
+ """
+ def__init__(self,properties:dict,filter:Union[dict,None]=None,obj_class=None):
+ ifobj_classisNone:
+ obj_class=XAText
+ super().__init__(properties,obj_class,filter)
+
+
[docs]defparagraphs(self,filter:dict=None)->'XAParagraphList':
+ """Gets the paragraphs of every text item in the list.
+
+ :return: The list of paragraphs
+ :rtype: XAParagraphList
+
+ .. versionadded:: 0.0.1
+ """
+ ls=[]
+ ifhasattr(self.xa_elem,"get"):
+ ls=self.xa_elem.arrayByApplyingSelector_("paragraphs")
+ else:
+ ls=[x.xa_elem.split("\n")forxinself]
+ ls=[paragraphforparagraphlistinlsforparagraphinparagraphlistifparagraph.strip()!='']
+ returnself._new_element(ls,XAParagraphList,filter)
+
+
[docs]defsentences(self)->'XASentenceList':
+ """Gets the sentences of every text item in the list.
+
+ :return: The list of sentences
+ :rtype: XASentenceList
+
+ .. versionadded:: 0.1.0
+ """
+ ls=[x.sentences()forxinself]
+ ls=[sentenceforsentencelistinlsforsentenceinsentencelist]
+ returnself._new_element(ls,XASentenceList)
+
+
[docs]defwords(self,filter:dict=None)->'XAWordList':
+ """Gets the words of every text item in the list.
+
+ :return: The list of words
+ :rtype: XAWordList
+
+ .. versionadded:: 0.0.1
+ """
+ ls=[]
+ ifhasattr(self.xa_elem,"get"):
+ ls=self.xa_elem.arrayByApplyingSelector_("words")
+ else:
+ ls=[x.xa_elem.split()forxinself]
+ ls=[wordforwordlistinlsforwordinwordlist]
+ returnself._new_element(ls,XAWordList,filter)
+
+
[docs]defcharacters(self,filter:dict=None)->'XACharacterList':
+ """Gets the characters of every text item in the list.
+
+ :return: The list of characters
+ :rtype: XACharacterList
+
+ .. versionadded:: 0.0.1
+ """
+ ls=[]
+ ifhasattr(self.xa_elem,"get"):
+ ls=self.xa_elem.arrayByApplyingSelector_("characters")
+ else:
+ ls=[list(x.xa_elem)forxinself]
+ ls=[characterforcharacterlistinlsforcharacterincharacterlist]
+ returnself._new_element(ls,XACharacterList,filter)
+
+
[docs]defattribute_runs(self,filter:dict=None)->'XAAttributeRunList':
+ """Gets the attribute runs of every text item in the list.
+
+ :return: The list of attribute runs
+ :rtype: XAAttributeRunList
+
+ .. versionadded:: 0.0.1
+ """
+ ls=[]
+ ifhasattr(self.xa_elem,"get"):
+ ls=self.xa_elem.arrayByApplyingSelector_("attributeRuns")
+ ls=[attribute_runforattribute_run_listinlsforattribute_runinattribute_run_list]
+ returnself._new_element(ls,XAAttributeRunList,filter)
+
+
[docs]defattachments(self,filter:dict=None)->'XAAttachmentList':
+ """Gets the attachments of every text item in the list.
+
+ :return: The list of attachments
+ :rtype: XAAttachmentList
+
+ .. versionadded:: 0.0.1
+ """
+ ls=[]
+ ifhasattr(self.xa_elem,"get"):
+ ls=self.xa_elem.arrayByApplyingSelector_("attachments")
+ ls=[attachmentforattachment_listinlsforattachmentinattachment_list]
+ returnself._new_element(ls,XAAttachmentList,filter)
+
+ def__repr__(self):
+ try:
+ ifisinstance(self.xa_elem[0],ScriptingBridge.SBObject):
+ # List items will not resolved to text upon dereferencing the list; need to resolve items individually
+ count=self.xa_elem.count()
+ ifcount<=500:
+ # Too many unresolved pointers, save time by just reporting the length
+ return"<"+str(type(self))+str([x.get()forxinself.xa_elem])+">"
+ return"<"+str(type(self))+"length: "+str(self.xa_elem.count())+">"
+
+ # List items will resolve to text upon dereferencing the list
+ return"<"+str(type(self))+str(self.xa_elem.get())+">"
+ except:
+ return"<"+str(type(self))+str(list(self.xa_elem))+">"
+
+
[docs]classXAText(XAObject):
+ """A class for managing and interacting with the text of documents.
+
+ .. versionadded:: 0.0.1
+ """
+ def__init__(self,properties):
+ ifisinstance(properties,dict):
+ super().__init__(properties)
+ elifisinstance(properties,str):
+ super().__init__({"element":properties})
+
+ self.text:str#: The plaintext contents of the rich text
+ self.color:XAColor#: The color of the first character
+ self.font:str#: The name of the font of the first character
+ self.size:int#: The size in points of the first character
+
+ @property
+ deftext(self)->str:
+ ifisinstance(self.xa_elem,str):
+ returnself.xa_elem
+ else:
+ returnself.xa_elem.text()
+
+ @text.setter
+ deftext(self,text:str):
+ ifisinstance(self.xa_elem,str):
+ self.xa_elem=text
+ else:
+ self.set_property("text",text)
+
+ @property
+ defcolor(self)->'XAColor':
+ ifisinstance(self.xa_elem,str):
+ returnNone
+ else:
+ returnXAColor(self.xa_elem.color())
+
+ @color.setter
+ defcolor(self,color:'XAColor'):
+ ifisinstance(self.xa_elem,str):
+ self.color=color.xa_elem
+ else:
+ self.set_property("color",color.xa_elem)
+
+ @property
+ deffont(self)->str:
+ ifisinstance(self.xa_elem,str):
+ returnNone
+ else:
+ returnself.xa_elem.font()
+
+ @font.setter
+ deffont(self,font:str):
+ ifisinstance(self.xa_elem,str):
+ self.font=font
+ else:
+ self.set_property("font",font)
+
+ @property
+ defsize(self)->int:
+ ifisinstance(self.xa_elem,str):
+ return0
+ else:
+ returnself.xa_elem.size()
+
+ @size.setter
+ defsize(self,size:int):
+ ifisinstance(self.xa_elem,str):
+ self.size=size
+ else:
+ self.set_property("size",size)
+
+ # def spelling_suggestions(self):
+ # suggestions = []
+ # text = str(self.xa_elem)
+ # spellchecker = AppKit.NSSpellChecker.sharedSpellChecker()
+
+ # orthography = None
+ # word_count = 0
+
+ # pprint(dir(LatentSemanticMapping.LSMMapCreate(None, 0)))
+
+ # # c = spellchecker.checkString_range_types_options_inSpellDocumentWithTag_orthography_wordCount_(text, (0, len(text)), AppKit.NSTextCheckingTypeSpelling | AppKit.NSTextCheckingTypeGrammar | AppKit.NSTextCheckingTypeCorrection, {}, 0, orthography, None)
+ # # print(c[1].languageMap())
+
+ # for word in text.split():
+ # completions = spellchecker.completionsForPartialWordRange_inString_language_inSpellDocumentWithTag_((0, len(word)), word, "", 0)
+ # suggestions.append(completions)
+
+ # # for word in text.split():
+ # # guesses = spellchecker.guessesForWordRange_inString_language_inSpellDocumentWithTag_((0, len(word)), word, "", 0)
+ # # suggestions.append(guesses)
+ # return suggestions
+
+
[docs]deftag_parts_of_speech(self,unit:Literal["word","sentence","paragraph","document"]="word")->list[tuple[str,str]]:
+ """Tags each word of the text with its associated part of speech.
+
+ :param unit: The grammatical unit to divide the text into for tagging, defaults to "word"
+ :type unit: Literal["word", "sentence", "paragraph", "document"]
+ :return: A list of tuples identifying each word of the text and its part of speech
+ :rtype: list[tuple[str, str]]
+
+ :Example 1: Extract nouns from a text
+
+ >>> import PyXA
+ >>> text = PyXA.XAText("Here’s to the crazy ones. The misfits. The rebels.")
+ >>> nouns = [pos[0] for pos in text.tag_parts_of_speech() if pos[1] == "Noun"]
+ >>> print(nouns)
+ ['ones', 'misfits', 'rebels']
+
+ .. versionadded:: 0.1.0
+ """
+ tagger=NaturalLanguage.NLTagger.alloc().initWithTagSchemes_([NaturalLanguage.NLTagSchemeLexicalClass])
+ tagger.setString_(str(self.xa_elem))
+
+ ifunit=="word":
+ unit=NaturalLanguage.NLTokenUnitWord
+ elifunit=="sentence":
+ unit=NaturalLanguage.NLTokenUnitSentence
+ elifunit=="paragraph":
+ unit=NaturalLanguage.NLTokenUnitParagraph
+ elifunit=="document":
+ unit=NaturalLanguage.NLTokenUnitDocument
+
+ tagged_pos=[]
+ defapply_tags(tag,token_range,error):
+ word_phrase=str(self.xa_elem)[token_range.location:token_range.location+token_range.length]
+ tagged_pos.append((word_phrase,tag))
+
+ tagger.enumerateTagsInRange_unit_scheme_options_usingBlock_((0,len(str(self.xa_elem))),unit,NaturalLanguage.NLTagSchemeLexicalClass,NaturalLanguage.NLTaggerOmitPunctuation|NaturalLanguage.NLTaggerOmitWhitespace,apply_tags)
+ returntagged_pos
+
+
[docs]deftag_languages(self,unit:Literal["word","sentence","paragraph","document"]="paragraph")->list[tuple[str,str]]:
+ """Tags each paragraph of the text with its language.
+
+ :param unit: The grammatical unit to divide the text into for tagging, defaults to "paragraph"
+ :type unit: Literal["word", "sentence", "paragraph", "document"]
+ :return: A list of tuples identifying each paragraph of the text and its language
+ :rtype: list[tuple[str, str]]
+
+ :Example:
+
+ >>> import PyXA
+ >>> text = PyXA.XAText("This is English.\nQuesto è Italiano.\nDas ist deutsch.\nこれは日本語です。")
+ >>> print(text.tag_languages())
+ [('This is English.\n', 'en'), ('Questo è Italiano.\n', 'it'), ('Das ist deutsch.\n', 'de'), ('これは日本語です。', 'ja')]
+
+ .. versionadded:: 0.1.0
+ """
+ tagger=NaturalLanguage.NLTagger.alloc().initWithTagSchemes_([NaturalLanguage.NLTagSchemeLanguage])
+ tagger.setString_(str(self.xa_elem))
+
+ ifunit=="word":
+ unit=NaturalLanguage.NLTokenUnitWord
+ elifunit=="sentence":
+ unit=NaturalLanguage.NLTokenUnitSentence
+ elifunit=="paragraph":
+ unit=NaturalLanguage.NLTokenUnitParagraph
+ elifunit=="document":
+ unit=NaturalLanguage.NLTokenUnitDocument
+
+ tagged_languages=[]
+ defapply_tags(tag,token_range,error):
+ paragraph=str(self.xa_elem)[token_range.location:token_range.location+token_range.length]
+ ifparagraph.strip()!="":
+ tagged_languages.append((paragraph,tag))
+
+ tagger.enumerateTagsInRange_unit_scheme_options_usingBlock_((0,len(str(self.xa_elem))),unit,NaturalLanguage.NLTagSchemeLanguage,NaturalLanguage.NLTaggerOmitPunctuation|NaturalLanguage.NLTaggerOmitWhitespace,apply_tags)
+ returntagged_languages
+
+
[docs]deftag_entities(self,unit:Literal["word","sentence","paragraph","document"]="word")->list[tuple[str,str]]:
+ """Tags each word of the text with either the category of entity it represents (i.e. person, place, or organization) or its part of speech.
+
+ :param unit: The grammatical unit to divide the text into for tagging, defaults to "word"
+ :type unit: Literal["word", "sentence", "paragraph", "document"]
+ :return: A list of tuples identifying each word of the text and its entity category or part of speech
+ :rtype: list[tuple[str, str]]
+
+ :Example:
+
+ >>> import PyXA
+ >>> text = PyXA.XAText("Tim Cook is the CEO of Apple.")
+ >>> print(text.tag_entities())
+ [('Tim', 'PersonalName'), ('Cook', 'PersonalName'), ('is', 'Verb'), ('the', 'Determiner'), ('CEO', 'Noun'), ('of', 'Preposition'), ('Apple', 'OrganizationName')]
+
+ .. versionadded:: 0.1.0
+ """
+ tagger=NaturalLanguage.NLTagger.alloc().initWithTagSchemes_([NaturalLanguage.NLTagSchemeNameTypeOrLexicalClass])
+ tagger.setString_(str(self.xa_elem))
+
+ ifunit=="word":
+ unit=NaturalLanguage.NLTokenUnitWord
+ elifunit=="sentence":
+ unit=NaturalLanguage.NLTokenUnitSentence
+ elifunit=="paragraph":
+ unit=NaturalLanguage.NLTokenUnitParagraph
+ elifunit=="document":
+ unit=NaturalLanguage.NLTokenUnitDocument
+
+ tagged_languages=[]
+ defapply_tags(tag,token_range,error):
+ word_phrase=str(self.xa_elem)[token_range.location:token_range.location+token_range.length]
+ ifword_phrase.strip()!="":
+ tagged_languages.append((word_phrase,tag))
+
+ tagger.enumerateTagsInRange_unit_scheme_options_usingBlock_((0,len(str(self.xa_elem))),unit,NaturalLanguage.NLTagSchemeNameTypeOrLexicalClass,NaturalLanguage.NLTaggerOmitPunctuation|NaturalLanguage.NLTaggerOmitWhitespace,apply_tags)
+ returntagged_languages
+
+
[docs]deftag_lemmas(self,unit:Literal["word","sentence","paragraph","document"]="word")->list[tuple[str,str]]:
+ """Tags each word of the text with its stem word.
+
+ :param unit: The grammatical unit to divide the text into for tagging, defaults to "word"
+ :type unit: Literal["word", "sentence", "paragraph", "document"]
+ :return: A list of tuples identifying each word of the text and its stem words
+ :rtype: list[tuple[str, str]]
+
+ :Example 1: Lemmatize each word in a text
+
+ >>> import PyXA
+ >>> text = PyXA.XAText("Here’s to the crazy ones. The misfits. The rebels.")
+ >>> print(text.tag_lemmas())
+ [('Here’s', 'here'), ('to', 'to'), ('the', 'the'), ('crazy', 'crazy'), ('ones', 'one'), ('The', 'the'), ('misfits', 'misfit'), ('The', 'the'), ('rebels', 'rebel')]
+
+ :Example 2: Combine parts of speech tagging and lemmatization
+
+ >>> import PyXA
+ >>> text = PyXA.XAText("The quick brown fox tries to jump over the sleeping lazy dog.")
+ >>> verbs = [pos[0] for pos in text.tag_parts_of_speech() if pos[1] == "Verb"]
+ >>> for index, verb in enumerate(verbs):
+ >>> print(index, PyXA.XAText(verb).tag_lemmas())
+ 0 [('tries', 'try')]
+ 1 [('jump', 'jump')]
+ 2 [('sleeping', 'sleep')]
+
+ .. versionadded:: 0.1.0
+ """
+ tagger=NaturalLanguage.NLTagger.alloc().initWithTagSchemes_([NaturalLanguage.NLTagSchemeLemma])
+ tagger.setString_(str(self.xa_elem))
+
+ ifunit=="word":
+ unit=NaturalLanguage.NLTokenUnitWord
+ elifunit=="sentence":
+ unit=NaturalLanguage.NLTokenUnitSentence
+ elifunit=="paragraph":
+ unit=NaturalLanguage.NLTokenUnitParagraph
+ elifunit=="document":
+ unit=NaturalLanguage.NLTokenUnitDocument
+
+ tagged_lemmas=[]
+ defapply_tags(tag,token_range,error):
+ word_phrase=str(self.xa_elem)[token_range.location:token_range.location+token_range.length]
+ ifword_phrase.strip()!="":
+ tagged_lemmas.append((word_phrase,tag))
+
+ tagger.enumerateTagsInRange_unit_scheme_options_usingBlock_((0,len(str(self.xa_elem))),unit,NaturalLanguage.NLTagSchemeLemma,NaturalLanguage.NLTaggerOmitPunctuation|NaturalLanguage.NLTaggerOmitWhitespace|NaturalLanguage.NLTaggerJoinContractions,apply_tags)
+ returntagged_lemmas
+
+
[docs]deftag_sentiments(self,sentiment_scale:list[str]=None,unit:Literal["word","sentence","paragraph","document"]="paragraph")->list[tuple[str,str]]:
+ """Tags each paragraph of the text with a sentiment rating.
+
+ :param sentiment_scale: A list of terms establishing a range of sentiments from most negative to most postive
+ :type sentiment_scale: list[str]
+ :param unit: The grammatical unit to divide the text into for tagging, defaults to "paragraph"
+ :type unit: Literal["word", "sentence", "paragraph", "document"]
+ :return: A list of tuples identifying each paragraph of the text and its sentiment rating
+ :rtype: list[tuple[str, str]]
+
+ :Example 1: Assess the sentiment of a string
+
+ >>> import PyXA
+ >>> text = PyXA.XAText("This sucks.\nBut this is great!")
+ >>> print(text.tag_sentiments())
+ [('This sucks.\n', 'Negative'), ('But this is great!', 'Positive')]
+
+ :Example 2: Use a custom sentiment scale
+
+ >>> import PyXA
+ >>> text = PyXA.XAText("This sucks.\nBut this is good!\nAnd this is great!")
+ >>> print(text.tag_sentiments(sentiment_scale=["Very Negative", "Negative", "Somewhat Negative", "Neutral", "Somewhat Positive", "Positive", "Very Positive"]))
+ [('This sucks.\n', 'Very Negative'), ('But this is good!\n', 'Neutral'), ('And this is great!', 'Very Positive')]
+
+ :Example 3: Use other tag units
+
+ >>> import PyXA
+ >>> text = PyXA.XAText("This sucks.\nBut this is good!\nAnd this is great!")
+ >>> print(1, text.tag_sentiments())
+ >>> print(2, text.tag_sentiments(unit="word"))
+ >>> print(3, text.tag_sentiments(unit="document"))
+ 1 [('This sucks.\n', 'Negative'), ('But this is good!\n', 'Neutral'), ('And this is great!', 'Positive')]
+ 2 [('This', 'Negative'), ('sucks', 'Negative'), ('.', 'Negative'), ('But', 'Neutral'), ('this', 'Neutral'), ('is', 'Neutral'), ('good', 'Neutral'), ('!', 'Neutral'), ('And', 'Positive'), ('this', 'Positive'), ('is', 'Positive'), ('great', 'Positive'), ('!', 'Positive')]
+ 3 [('This sucks.\nBut this is good!\nAnd this is great!', 'Neutral')]
+
+ .. versionadded:: 0.1.0
+ """
+ ifsentiment_scaleisNoneorlen(sentiment_scale)==0:
+ sentiment_scale=["Negative","Neutral","Positive"]
+
+ ifunit=="word":
+ unit=NaturalLanguage.NLTokenUnitWord
+ elifunit=="sentence":
+ unit=NaturalLanguage.NLTokenUnitSentence
+ elifunit=="paragraph":
+ unit=NaturalLanguage.NLTokenUnitParagraph
+ elifunit=="document":
+ unit=NaturalLanguage.NLTokenUnitDocument
+
+ tagger=NaturalLanguage.NLTagger.alloc().initWithTagSchemes_([NaturalLanguage.NLTagSchemeSentimentScore])
+ tagger.setString_(str(self.xa_elem))
+
+ tagged_sentiments=[]
+ defapply_tags(tag,token_range,error):
+ paragraph=str(self.xa_elem)[token_range.location:token_range.location+token_range.length]
+ ifparagraph.strip()!="":
+ # Map raw tag value to range length
+ raw_value=float(tagor0)
+ scaled=(raw_value+1.0)/2.0*(len(sentiment_scale)-1)
+
+ label=sentiment_scale[int(scaled)]
+ tagged_sentiments.append((paragraph,label))
+
+ tagger.enumerateTagsInRange_unit_scheme_options_usingBlock_((0,len(self.xa_elem)),unit,NaturalLanguage.NLTagSchemeSentimentScore,0,apply_tags)
+ returntagged_sentiments
+
+
[docs]defparagraphs(self,filter:dict=None)->'XAParagraphList':
+ """Gets a list of paragraphs in the text.
+
+ :param filter: The properties and associated values to filter paragraphs by, defaults to None
+ :type filter: dict, optional
+ :return: The list of paragraphs
+ :rtype: XAParagraphList
+
+ :Example 1: Get paragraphs of a text string
+
+ >>> import PyXA
+ >>> string = \"\"\"This is the first paragraph.
+ >>>
+ >>> This is the second paragraph.\"\"\"
+ >>> text = PyXA.XAText(string)
+ >>> print(text.paragraphs())
+ <<class 'PyXA.XAWordList'>['This is the first paragraph.', 'This is the second paragraph. Neat! Very cool.']>
+
+ :Example 2: Get paragraphs of a Note
+
+ >>> import PyXA
+ >>> app = PyXA.Application("Notes")
+ >>> note = app.notes()[0]
+ >>> text = PyXA.XAText(note.plaintext)
+ >>> print(text.paragraphs())
+ <<class 'PyXA.XAWordList'>['This is the first paragraph.', 'This is the second paragraph. Neat! Very cool.']>
+
+ .. versionadded:: 0.0.1
+ """
+ ifisinstance(self.xa_elem,str):
+ ls=[xforxinself.xa_elem.split("\n")ifx.strip()!='']
+ returnself._new_element(ls,XAWordList,filter)
+ else:
+ returnself._new_element(self.xa_elem.paragraphs(),XAParagraphList,filter)
+
+
[docs]defsentences(self)->'XASentenceList':
+ """Gets a list of sentences in the text.
+
+ :return: The list of sentencnes
+ :rtype: XASentenceList
+
+ :Example:
+
+ >>> import PyXA
+ >>> app = PyXA.Application("Notes")
+ >>> note = app.notes()[0]
+ >>> text = PyXA.XAText(note.plaintext)
+ >>> print(text.sentences())
+ <<class 'PyXA.XASentenceList'>['This is the first paragraph.\\n', '\\n', 'This is the second paragraph. ', 'Neat! ', 'Very cool.']>
+
+ .. versionadded:: 0.1.0
+ """
+ raw_string=self.xa_elem
+ ifhasattr(self.xa_elem,"get"):
+ raw_string=self.xa_elem.get()
+
+ sentences=[]
+ tokenizer=AppKit.NLTokenizer.alloc().initWithUnit_(AppKit.kCFStringTokenizerUnitSentence)
+ tokenizer.setString_(raw_string)
+ forchar_rangeintokenizer.tokensForRange_((0,len(raw_string))):
+ start=char_range.rangeValue().location
+ end=start+char_range.rangeValue().length
+ sentences.append(raw_string[start:end])
+
+ ls=AppKit.NSArray.alloc().initWithArray_(sentences)
+ returnself._new_element(sentences,XASentenceList)
+
+
[docs]defwords(self,filter:dict=None)->'XAWordList':
+ """Gets a list of words in the text.
+
+ :return: The list of words
+ :rtype: XAWordList
+
+ :Example:
+
+ >>> import PyXA
+ >>> app = PyXA.Application("Notes")
+ >>> note = app.notes()[0]
+ >>> text = PyXA.XAText(note.plaintext)
+ >>> print(text.words())
+ <<class 'PyXA.XAWordList'>['This', 'is', 'the', 'first', 'paragraph.', 'This', 'is', 'the', 'second', 'paragraph.', 'Neat!', 'Very', 'cool.']>
+
+ .. versionadded:: 0.0.1
+ """
+ ifisinstance(self.xa_elem,str):
+ ls=self.xa_elem.split()
+ returnself._new_element(ls,XAWordList,filter)
+ else:
+ returnself._new_element(self.xa_elem.words(),XAWordList,filter)
+
+
[docs]defcharacters(self,filter:dict=None)->'XACharacterList':
+ """Gets a list of characters in the text.
+
+ :return: The list of characters
+ :rtype: XACharacterList
+
+ :Example 1: Get all characters in a text
+
+ >>> import PyXA
+ >>> app = PyXA.Application("Notes")
+ >>> note = app.notes()[0]
+ >>> text = PyXA.XAText(note.plaintext)
+ >>> print(text.characters())
+ <<class 'PyXA.XACharacterList'>['T', 'h', 'i', 's', ' ', 'i', 's', ' ', 't', 'h', 'e', ' ', 'f', 'i', 'r', 's', 't', ' ', 'p', 'a', 'r', 'a', 'g', 'r', 'a', 'p', 'h', '.', '\n', '\n', 'T', 'h', 'i', 's', ' ', 'i', 's', ' ', 't', 'h', 'e', ' ', 's', 'e', 'c', 'o', 'n', 'd', ' ', 'p', 'a', 'r', 'a', 'g', 'r', 'a', 'p', 'h', '.', ' ', 'N', 'e', 'a', 't', '!', ' ', 'V', 'e', 'r', 'y', ' ', 'c', 'o', 'o', 'l', '.']>
+
+ :Example 2: Get the characters of the first word in a text
+
+ >>> import PyXA
+ >>> app = PyXA.Application("Notes")
+ >>> note = app.notes()[0]
+ >>> text = PyXA.XAText(note.plaintext)
+ >>> print(text.words()[0].characters())
+ <<class 'PyXA.XACharacterList'>['T', 'h', 'i', 's']>
+
+ .. versionadded:: 0.0.1
+ """
+ ifisinstance(self.xa_elem,str):
+ ls=list(self.xa_elem)
+ returnself._new_element(ls,XACharacterList,filter)
+ else:
+ returnself._new_element(self.xa_elem.characters().get(),XACharacterList,filter)
+
+
[docs]defattribute_runs(self,filter:dict=None)->'XAAttributeRunList':
+ """Gets a list of attribute runs in the text. For formatted text, this returns all sequences of characters sharing the same attributes.
+
+ :param filter: The properties and associated values to filter attribute runs by, defaults to None
+ :type filter: dict, optional
+ :return: The list of attribute runs
+ :rtype: XAAttributeRunList
+
+ .. versionadded:: 0.0.1
+ """
+ ifisinstance(self.xa_elem,str):
+ return[]
+ else:
+ returnself._new_element(self.xa_elem.attributeRuns(),XAAttributeRunList,filter)
+
+
[docs]defattachments(self,filter:dict=None)->'XAAttachmentList':
+ """Gets a list of attachments of the text.
+
+ :param filter: The properties and associated values to filter attachments by, defaults to None
+ :type filter: dict, optional
+ :return: The list of attachments
+ :rtype: XAAttachmentList
+
+ .. versionadded:: 0.0.1
+ """
+ ifisinstance(self.xa_elem,str):
+ return[]
+ else:
+ returnself._new_element(self.xa_elem.attachments(),XAAttachmentList,filter)
[docs]classXAParagraphList(XATextList):
+ """A wrapper around lists of paragraphs that employs fast enumeration techniques.
+
+ .. versionadded:: 0.0.5
+ """
+ def__init__(self,properties:dict,filter:Union[dict,None]=None):
+ super().__init__(properties,filter,XAParagraph)
+
+
[docs]classXAParagraph(XAText):
+ """A class for managing and interacting with paragraphs in text documents.
+
+ .. versionadded:: 0.0.1
+ """
+ def__init__(self,properties):
+ super().__init__(properties)
+
+
+
+
[docs]classXASentenceList(XATextList):
+ """A wrapper around lists of sentences that employs fast enumeration techniques.
+
+ .. versionadded:: 0.0.5
+ """
+ def__init__(self,properties:dict,filter:Union[dict,None]=None):
+ super().__init__(properties,filter,XASentence)
+
+
[docs]classXASentence(XAText):
+ """A class for managing and interacting with sentences in text documents.
+
+ .. versionadded:: 0.0.1
+ """
+ def__init__(self,properties):
+ super().__init__(properties)
+
+
+
+
+
[docs]classXAWordList(XATextList):
+ """A wrapper around lists of words that employs fast enumeration techniques.
+
+ .. versionadded:: 0.0.5
+ """
+ def__init__(self,properties:dict,filter:Union[dict,None]=None):
+ super().__init__(properties,filter,XAWord)
+
+
[docs]classXAWord(XAText):
+ """A class for managing and interacting with words in text documents.
+
+ .. versionadded:: 0.0.1
+ """
+ def__init__(self,properties):
+ super().__init__(properties)
+
+
+
+
+
[docs]classXACharacterList(XATextList):
+ """A wrapper around lists of characters that employs fast enumeration techniques.
+
+ .. versionadded:: 0.0.5
+ """
+ def__init__(self,properties:dict,filter:Union[dict,None]=None):
+ super().__init__(properties,filter,XACharacter)
+
+
[docs]classXACharacter(XAText):
+ """A class for managing and interacting with characters in text documents.
+
+ .. versionadded:: 0.0.1
+ """
+ def__init__(self,properties):
+ super().__init__(properties)
+
+
+
+
+
[docs]classXAAttributeRunList(XATextList):
+ """A wrapper around lists of attribute runs that employs fast enumeration techniques.
+
+ .. versionadded:: 0.0.5
+ """
+ def__init__(self,properties:dict,filter:Union[dict,None]=None):
+ super().__init__(properties,filter,XAAttributeRun)
+
+
[docs]classXAAttributeRun(XAText):
+ """A class for managing and interacting with attribute runs in text documents.
+
+ .. versionadded:: 0.0.1
+ """
+ def__init__(self,properties):
+ super().__init__(properties)
+
+
+
+
+
[docs]classXAAttachmentList(XATextList):
+ """A wrapper around lists of text attachments that employs fast enumeration techniques.
+
+ .. versionadded:: 0.0.5
+ """
+ def__init__(self,properties:dict,filter:Union[dict,None]=None):
+ super().__init__(properties,filter,XAAttachment)
+
+
[docs]classXAAttachment(XAObject):
+ """A class for managing and interacting with attachments in text documents.
+
+ .. versionadded:: 0.0.1
+ """
+ def__init__(self,properties):
+ super().__init__(properties)
+
+
+
+
+
[docs]classXALSM(XAObject):
+ def__init__(self,dataset:Union[dict[str,list[str]],None]=None,from_file:bool=False):
+ """Initializes a Latent Semantic Mapping environment.
+
+ :param dataset: The initial dataset, specified as a dictionary where keys are categories and values are list of corresponding texts, defaults to None. Cannot be None if from_file is False.
+ :type dataset: Union[dict[str, list[str]], None], optional
+ :param from_file: Whether the LSM is being loaded from a file, defaults to False. Cannot be False is dataset is None.
+ :type from_file: bool, optional
+ :raises ValueError: Either you must provide a dataset, or you must load an existing map from an external file
+
+ :Example 1: Classify emails based on subject line
+
+ >>> import PyXA
+ >>> lsm = PyXA.XALSM({
+ >>> # 1
+ >>> "spam": ["Deals", "Holiday playbook", "Spend and save. You know the drill.", "Don't miss these holiday deals!", "GOOD NEWS", "you will never have an opportunity of this kind again", "Your Long Overdue Compensation Funds; Totally", "US $25,000,000.00", "goog day", "GOOD DAY, I am Mike Paul I have a", "enron methanol; meter # : 988291 this is a follow up to the note i gave you on monday , 4...", "hpl nom for january 9, see attached file : hplnol 09. xls", "neon retreat ho ho ho, we're around to that most wonderful time of the year", "photoshop, windows, office cheap, main trending abasements, darer prudently fortuitous", "re: indian springs this deal is to book the teco pvr revenue. it is my understanding that...", "noms / actual flow for 2 / we agree", "nominations for oct 21 - 23"],
+ >>>
+ >>> # 2
+ >>> "kayak": ["Price Alert: Airfare holding steady for your trip", "Prices going down for your Boston to Dublin flight", "Price Increase: Boston to Dublin airfare up $184", "Flight Alert: #37 decrease on your flight to Dublin.", "Flight Alert: It's time to book your flight to Dublin", "Price Alert: Airfare holding steady for your Bangor, ME to...", "Ready to explore the world again?"],
+ >>>
+ >>> # 3
+ >>> "lenovo": ["Doorbuster deals up to 70% off", "Visionary, On-Demand Content. Lenovo Tech World '22 is starting", "Up to 70% off deals 9 AM", "TGIF! Here's up to 70% off to jumpstart your weekend", "Top picks to refresh your workspace", "This only happens twice a year", "Think about saving on a Think PC", "Deep deals on Summer Clearance", "Save up to 67% + earn rewards", "Unlock up to 61% off Think PCs", "Giveaway alert!", "Annual Sale Sneak Peak Unlocked!"],
+ >>>
+ >>> # 4
+ >>> "linkedin": ["Here is the latest post trending amongst your coworkers", "Stephen, add Sean Brown to your network", "Share thoughts on LinkedIn", "Top companies are hiring", "Linkedin is better on the app", "Here is the latest post trending amongst your coworkers", "Stephen, add Ronald McDonald to your network", "James Smith shared a post for the first time in a while", "Here is the latest post trending amongst your coworkers", "You appeared in 13 searches this week", "you're on a roll with your career!", "You appeared in 16 searches this week", "18 people notices you", "You appeared in 10 searches this week", "Stephen, add Joe Shmoe to your network", "Your network is talking: The Center for Oceanic Research...", "thanks for being a valued member"]
+ >>> })
+ >>> print(lsm.categorize_query("New! Weekend-only deals"))
+ >>> print(lsm.categorize_query("Stephen, redeem these three (3) unlocked courses"))
+ >>> print(lsm.categorize_query("Round Trip From San Francisco to Atlanta"))
+ [(3, 0.9418474435806274)]
+ [(4, 0.9366401433944702)]
+ [(2, 0.9944692850112915)]
+
+ :Example 2: Use the Mail module to automate dataset construction
+
+ >>> import PyXA
+ >>> app = PyXA.Application("Mail")
+ >>> junk_subject_lines = app.accounts()[0].mailboxes().by_name("Junk").messages().subject()
+ >>> other_subject_lines = app.accounts()[0].mailboxes().by_name("INBOX").messages().subject()
+ >>>
+ >>> dataset = {
+ >>> "junk": junk_subject_lines,
+ >>> "other": other_subject_lines
+ >>> }
+ >>> lsm = PyXA.XALSM(dataset)
+ >>>
+ >>> query = "Amazon Web Services Billing Statement Available"
+ >>> category = list(dataset.keys())[lsm.categorize_query(query)[0][0] - 1]
+ >>> print(query, "- category:", category)
+ >>>
+ >>> query = "Complete registration form asap receive your rewards"
+ >>> category = list(dataset.keys())[lsm.categorize_query(query)[0][0] - 1]
+ >>> print(query, "- category:", category)
+ Amazon Web Services Billing Statement Available - category: other
+ Complete registration form asap receive your rewards - category: junk
+
+ .. versionadded:: 0.1.0
+ """
+ self.__categories={}
+ ifdatasetisNoneandnotfrom_file:
+ raiseValueError("You must either load a map from an external file or provide an initial dataset.")
+ elifdatasetisNone:
+ # Map will be loaded from external file -- empty dataset is temporary
+ self.__dataset={}
+ else:
+ # Create new map
+ self.__dataset=dataset
+
+ self.map=LatentSemanticMapping.LSMMapCreate(None,0)
+ LatentSemanticMapping.LSMMapStartTraining(self.map)
+ LatentSemanticMapping.LSMMapSetProperties(self.map,{
+ LatentSemanticMapping.kLSMSweepCutoffKey:0,
+ # LatentSemanticMapping.kLSMPrecisionKey: LatentSemanticMapping.kLSMPrecisionDouble,
+ LatentSemanticMapping.kLSMAlgorithmKey:LatentSemanticMapping.kLSMAlgorithmSparse,
+ })
+
+ forcategoryindataset:
+ self.__add_category(category)
+
+ LatentSemanticMapping.LSMMapCompile(self.map)
+
+ def__add_category(self,category:str)->int:
+ loc=Foundation.CFLocaleGetSystem()
+ category_ref=LatentSemanticMapping.LSMMapAddCategory(self.map)
+ self.__categories[category]=category_ref
+ self.__categories[category_ref]=category_ref
+ text_ref=LatentSemanticMapping.LSMTextCreate(None,self.map)
+ LatentSemanticMapping.LSMTextAddWords(text_ref," ".join(self.__dataset[category]),loc,LatentSemanticMapping.kLSMTextPreserveAcronyms)
+ LatentSemanticMapping.LSMMapAddText(self.map,text_ref,category_ref)
+ returncategory_ref
+
+
[docs]defsave(self,file_path:Union[XAPath,str])->bool:
+ """Saves the map to an external file.
+
+ :param file_path: The path to save the map at
+ :type file_path: Union[XAPath, str]
+ :return: True if the map was saved successfully
+ :rtype: bool
+
+ :Example: Create a Reddit post classifier for gaming vs. productivity posts
+
+ >>> import PyXA
+ >>> lsm = PyXA.XALSM({
+ >>> # 1
+ >>> "gaming": ["If you could vote on the 2017 Mob Vote again, which mob would you choose this time and why?", "Take your time, you got this", "My parents (late 70s) got me a ps5 controller for Christmas. I do not own a playstation 5...", "I got off the horse by accident right before a cutscene in red dead", "boy gamer", "Minesweeper 99 x 99, 1500 mines. Took me about 2.5 hours to finish, nerve-wracking. No one might care, but just wanted to share this.", "The perfect cosplay doesn’t ex...", "'Play until we lose'", "Can we please boycott Star Wars battlefront 2", "EA removed the refund button on their webpage, and now you have to call them and wait to get a refund.", "Train Simulator is so immersive!", "Been gaming with this dude for 15 years. Since Rainbow Six Vegas on 360. I have some good gaming memories with him. He tried but couldn’t get one. Little did he know I was able to get him one. Looking forward to playing another generation with him.", "EA will no longer have exclusive rights of the Star Wars games", "A ziplining contraption I created with 1000+ command blocks", "The steepest walkable staircase possible in 1.16", "I made a texture pack that gives mobs different facial expressions. Should I keep going?"],
+ >>>
+ >>> # 2
+ >>> "productivity": ["Looking for an alarm app that plays a really small alarm, doesn’t need to be switched off and doesn’t repeat.", "I want to build a second brain but I'm lost and don't know where to start.", "noise cancelling earplugs", "I have so much to do but I don't know where to start", "How to handle stressful work calls", "time tracking app/platform", "We just need to find ways to cope and keep moving forward.", "Ikigai - A Reason for Being", "Minimalist Productivity Tip: create two users on your computer ➞ One for normal use and leisure ➞ One for business/work only. I have nothing except the essentials logged in on my work user. Not even Messages or YouTube. It completely revolutionized my productivity 💸", "Trick yourself into productivity the same way you trick yourself into procrastination", "I spent 40 hours sifting through research papers to fix my mental clarity, focus, and productivity - I ended up going down a rabbit hole and figuring out it was all tied to sleep, even though I felt I sleep well - here's what I found.", "The Cycle of Procrastination. Always a good reminder", "'Most people underestimate what they can do in a year, and overestimate what they can do in a day' - When you work on getting 1% better each day you won't even recognize yourself in a year."],
+ >>> })
+ >>> lsm.save("/Users/steven/Downloads/gaming-productivity.map")
+
+ .. versionadded:: 0.1.0
+ """
+ ifisinstance(file_path,str):
+ file_path=XAPath(file_path)
+
+ status=LatentSemanticMapping.LSMMapWriteToURL(self.map,file_path.xa_elem,0)
+ ifstatus==0:
+ returnTrue
+ returnFalse
+
+
[docs]defload(file_path:Union[XAPath,str])->'XALSM':
+ """Loads a map from an external file.
+
+ :param file_path: The file path for load the map from
+ :type file_path: Union[XAPath, str]
+ :return: The populated LSM object
+ :rtype: XALSM
+
+ :Example: Using the gaming vs. productivity Reddit post map
+
+ >>> import PyXA
+ >>> lsm = PyXA.XALSM.load("/Users/steven/Downloads/gaming-productivity.map")
+ >>> print(lsm.categorize_query("Hidden survival base on our server"))
+ >>> print(lsm.categorize_query("Your memory is FAR more powerful than you think… school just never taught us to use it properly."))
+ [(1, 0.7313863635063171)]
+ [(2, 0.9422407150268555)]
+
+ .. versionadded:: 0.1.0
+ """
+ ifisinstance(file_path,str):
+ file_path=XAPath(file_path)
+
+ new_lsm=XALSM(from_file=True)
+ new_lsm.map=LatentSemanticMapping.LSMMapCreateFromURL(None,file_path.xa_elem,LatentSemanticMapping.kLSMMapLoadMutable)
+ new_lsm.__dataset={i:[]foriinrange(LatentSemanticMapping.LSMMapGetCategoryCount(new_lsm.map))}
+ new_lsm.__categories={i:iforiinrange(LatentSemanticMapping.LSMMapGetCategoryCount(new_lsm.map))}
+ LatentSemanticMapping.LSMMapCompile(new_lsm.map)
+ returnnew_lsm
+
+
[docs]defadd_category(self,name:str,initial_data:Union[list[str],None]=None)->int:
+ """Adds a new category to the map, optionally filling the category with initial text data.
+
+ :param name: The name of the category
+ :type name: str
+ :param initial_data: _description_
+ :type initial_data: list[str]
+ :return: The ID of the new category
+ :rtype: int
+
+ :Example: Add a category for cleaning-related Reddit posts to the previous example
+
+ >>> import PyXA
+ >>> lsm = PyXA.XALSM.load("/Users/steven/Downloads/gaming-productivity.map")
+ >>> lsm.add_category("cleaning", ["Curtains stained from eyelet reaction at dry cleaner", "How do I get these stains out of my pink denim overalls? from a black denim jacket that was drying next to them", "Cleaned my depression room after months 🥵", "Tip: 30 minute soak in Vinegar", "Regular floor squeegee pulled a surprising amount of pet hair out of my carpet!", "Before and after…", "It actually WORKS", "CLR is actually magic. (With some elbow grease)", "It was 100% worth it to scrape out my old moldy caulk and replace it. $5 dollars and a bit of time to make my shower look so much cleaner!", "Thanks to the person who recommended the Clorox Foamer. Before and after pics", "TIL you can dissolve inkstains with milk.", "Fixing cat scratch marks to couch using felting needle: Before and After", "Turns out BKF isn't a meme! Really satisfied with this stuff"])
+ >>> print(lsm.categorize_query("Hidden survival base on our server"))
+ >>> print(lsm.categorize_query("Your memory is FAR more powerful than you think… school just never taught us to use it properly."))
+ >>> print(lsm.categorize_query("A carpet rake will change your life."))
+ [(1, 0.7474805116653442)]
+ [(2, 0.7167008519172668)]
+ [(3, 0.797333300113678)]
+
+ .. versionadded:: 0.1.0
+ """
+ LatentSemanticMapping.LSMMapStartTraining(self.map)
+
+ ifinitial_dataisNone:
+ initial_data=[]
+
+ ifnameinself.__dataset:
+ raiseValueError("The category name must be unique.")
+
+ self.__dataset[name]=initial_data
+ category_ref=self.__add_category(name)
+ LatentSemanticMapping.LSMMapCompile(self.map)
+ returncategory_ref
+
+
[docs]defadd_data(self,data:dict[Union[int,str],list[str]])->list[int]:
+ """Adds the provided data, organized by category, to the active map.
+
+ :param data: A dictionary specifying new or existing categories along with data to input into them
+ :type data: dict[Union[int, str], list[str]]
+ :return: A list of newly created category IDs
+ :rtype: int
+
+ :Example: Classify text by language
+
+ >>> import PyXA
+ >>> lsm = PyXA.XALSM({})
+ >>> lsm.add_data({
+ >>> # 1
+ >>> "english": ["brilliance outer jacket artist flat mosquito recover restrict official gas ratio publish domestic realize pure offset obstacle thigh favorite demonstration revive nest reader slide pudding symptom ballot auction characteristic complete Mars ridge student explosion dive emphasis the buy perfect motif penny a errand to fur far spirit random integration of with"],
+ >>>
+ >>> # 2
+ >>> "italian": ["da piazza proposta di legge legare nazionale a volte la salute bar farti farmi il pane aggiunta valore artista chiamata settentrionale scuro buio classe signori investitore in grado di fidanzato tagliare arriva successo altrimenti speciale esattamente definizione sorriso chiamo madre pulire esperto rurale vedo malattia era amici libertà l'account immaginare lingua soldi più perché"],
+ >>> })
+ >>> print(lsm.categorize_query("Here's to the crazy ones"))
+ >>> print(lsm.categorize_query("Potete parlarmi in italiano"))
+ [(1, 1.0)]
+ [(2, 1.0)]
+
+ .. versionadded:: 0.1.0
+ """
+ category_refs=[]
+ LatentSemanticMapping.LSMMapStartTraining(self.map)
+ forcategoryindata:
+ ifcategorynotinself.__dataset:
+ self.__dataset[category]=data[category]
+ category_refs.append(self.__add_category(category))
+ else:
+ loc=Foundation.CFLocaleGetSystem()
+ text_ref=LatentSemanticMapping.LSMTextCreate(None,self.map)
+ LatentSemanticMapping.LSMTextAddWords(text_ref," ".join(data[category]),loc,LatentSemanticMapping.kLSMTextPreserveAcronyms)
+ LatentSemanticMapping.LSMMapAddText(self.map,text_ref,self.__categories[category])
+ LatentSemanticMapping.LSMMapCompile(self.map)
+ returncategory_refs
+
+
[docs]defadd_text(self,text:str,category:Union[int,str],weight:float=1):
+ """Adds the given text to the specified category, applying an optional weight.
+
+ :param text: The text to add to the dataset
+ :type text: str
+ :param category: The category to add the text to
+ :type category: Union[int, str]
+ :param weight: The weight to assign to the text entry, defaults to 1
+ :type weight: float, optional
+ :raises ValueError: The specified category must be a valid category name or ID
+
+ :Example:
+
+ >>> import PyXA
+ >>> lsm = PyXA.XALSM({"colors": [], "numbers": ["One", "Two", "Three"]})
+ >>> lsm.add_text("red orange yellow green blue purple", "colors")
+ >>> lsm.add_text("white black grey gray brown pink", 1)
+ >>> print(lsm.categorize_query("pink"))
+
+ .. versionadded:: 0.1.0
+ """
+ LatentSemanticMapping.LSMMapStartTraining(self.map)
+ ifcategorynotinself.__datasetandcategorynotinself.__categories:
+ raiseValueError(f"Invalid category: {category}")
+
+ loc=Foundation.CFLocaleGetSystem()
+ text_ref=LatentSemanticMapping.LSMTextCreate(None,self.map)
+ LatentSemanticMapping.LSMTextAddWords(text_ref,text,loc,LatentSemanticMapping.kLSMTextPreserveAcronyms)
+ LatentSemanticMapping.LSMMapAddTextWithWeight(self.map,text_ref,self.__categories[category],weight)
+ LatentSemanticMapping.LSMMapCompile(self.map)
+
+
[docs]defcategorize_query(self,query:str,num_results:int=1)->list[tuple[int,float]]:
+ """Categorizes the query based on the current weights in the map.
+
+ :param query: The query to categorize
+ :type query: str
+ :param num_results: The number of categorizations to show, defaults to 1
+ :type num_results: int, optional
+ :return: A list of tuples identifying categories and their associated score. A higher score indicates better fit. If not matching categorization is found, the list will be empty.
+ :rtype: list[tuple[int, float]]
+
+ :Example:
+
+ >>> import PyXA
+ >>> dataset = {
+ >>> # 1
+ >>> "color": ["red", "orange", "yellow", "green", "emerald", "blue", "purple", "white", "black", "brown", "pink", "grey", "gray"],
+ >>>
+ >>> # 2
+ >>> "number": ["One Two Three Four Five Six Seven Eight Nine Ten"]
+ >>> }
+ >>> lsm = PyXA.XALSM(dataset)
+ >>> queries = ["emerald green three", "one hundred five", "One o' clock", "sky blue", "ninety nine", "purple pink"]
+ >>>
+ >>> for query in queries:
+ >>> category = "Unknown"
+ >>> categorization_tuple = lsm.categorize_query(query)
+ >>> if len(categorization_tuple) > 0:
+ >>> category = list(dataset.keys())[categorization_tuple[0][0] - 1]
+ >>> print(query, "is a", category)
+ emerald green three is a color
+ one hundred five is a number
+ One o' clock is a number
+ sky blue is a color
+ ninety nine is a number
+ purple pink is a color
+
+ .. versionadded:: 0.1.0
+ """
+ loc=Foundation.CFLocaleGetSystem()
+ text_ref=LatentSemanticMapping.LSMTextCreate(None,self.map)
+ LatentSemanticMapping.LSMTextAddWords(text_ref,query,loc,0)
+ rows=LatentSemanticMapping.LSMResultCreate(None,self.map,text_ref,10,LatentSemanticMapping.kLSMTextPreserveAcronyms)
+
+ categorization=[]
+ num_results=min(num_results,LatentSemanticMapping.LSMResultGetCount(rows))
+ foriinrange(0,num_results):
+ category_num=LatentSemanticMapping.LSMResultGetCategory(rows,i)
+ score=LatentSemanticMapping.LSMResultGetScore(rows,i)
+ categorization.append((category_num,score))
+ returncategorization
+
+
+
+
+
[docs]classXAColorList(XATextList):
+ """A wrapper around lists of colors that employs fast enumeration techniques.
+
+ .. versionadded:: 0.0.6
+ """
+ def__init__(self,properties:dict,filter:Union[dict,None]=None):
+ super().__init__(properties,XAColor,filter)
+
+
[docs]classXAColor(XAObject,XAClipboardCodable):
+ def__init__(self,*args):
+ iflen(args)==0:
+ # No color specified -- default to white
+ self.xa_elem=XAColor.white_color().xa_elem
+ eliflen(args)==1andisinstance(args[0],AppKit.NSColor):
+ # Initialize copy of non-mutable NSColor object
+ self.copy_color(args[0])
+ eliflen(args)==1andisinstance(args[0],XAColor):
+ # Initialize copy of another XAColor object
+ self.copy_color(args[0].xa_elem)
+ else:
+ # Initialize from provided RGBA values
+ red=args[0]iflen(args)>=0else255
+ green=args[1]iflen(args)>=1else255
+ blue=args[2]iflen(args)>=3else255
+ alpha=args[3]iflen(args)==4else1.0
+ self.xa_elem=AppKit.NSCalibratedRGBColor.alloc().initWithRed_green_blue_alpha_(red,green,blue,alpha)
+
+
[docs]defred()->'XAColor':
+ """Initializes and returns a pure red :class:`XAColor` object.
+
+ .. versionadded:: 0.1.0
+ """
+ returnXAColor(65535,0,0)
+
+
[docs]deforange()->'XAColor':
+ """Initializes and returns an :class:`XAColor` object whose RGB values are (1.0, 0.5, 0.0).
+
+ .. versionadded:: 0.1.0
+ """
+ returnXAColor(AppKit.NSColor.orangeColor())
+
+
[docs]defyellow()->'XAColor':
+ """Initializes and returns an :class:`XAColor` object whose RGB values are (1.0, 1.0, 0.0).
+
+ .. versionadded:: 0.1.0
+ """
+ returnXAColor(AppKit.NSColor.yellowColor())
+
+
[docs]defgreen()->'XAColor':
+ """Initializes and returns a pure green :class:`XAColor` object.
+
+ .. versionadded:: 0.1.0
+ """
+ returnXAColor(0,65535,0)
+
+
[docs]defcyan()->'XAColor':
+ """Initializes and returns an :class:`XAColor` object whose RGB values are (0.0, 1.0, 1.0).
+
+ .. versionadded:: 0.1.0
+ """
+ returnXAColor(AppKit.NSColor.cyanColor())
+
+
[docs]defblue()->'XAColor':
+ """Initializes and returns a pure blue :class:`XAColor` object.
+
+ .. versionadded:: 0.1.0
+ """
+ returnXAColor(0,0,65535)
+
+
[docs]defmagenta()->'XAColor':
+ """Initializes and returns an :class:`XAColor` object whose RGB values are (1.0, 0.0, 1.0).
+
+ .. versionadded:: 0.1.0
+ """
+ returnXAColor(AppKit.NSColor.magentaColor())
+
+
[docs]defpurple()->'XAColor':
+ """Initializes and returns an :class:`XAColor` object whose RGB values are (0.5, 0.0, 0.5).
+
+ .. versionadded:: 0.1.0
+ """
+ returnXAColor(AppKit.NSColor.purpleColor())
+
+
[docs]defbrown()->'XAColor':
+ """Initializes and returns an :class:`XAColor` object whose RGB values are (0.6, 0.4, 0.2).
+
+ .. versionadded:: 0.1.0
+ """
+ returnXAColor(AppKit.NSColor.brownColor())
+
+
[docs]defwhite()->'XAColor':
+ """Initializes and returns a pure white :class:`XAColor` object.
+
+ .. versionadded:: 0.1.0
+ """
+ returnXAColor(65535,65535,65535)
+
+
[docs]defgray()->'XAColor':
+ """Initializes and returns an :class:`XAColor` object whose RGB values are (0.5, 0.5, 0.5).
+
+ .. versionadded:: 0.1.0
+ """
+ returnXAColor(0.5,0.5,0.5)
+
+
[docs]defblack()->'XAColor':
+ """Initializes and returns a pure black :class:`XAColor` object.
+
+ .. versionadded:: 0.1.0
+ """
+ returnXAColor(0,0,0)
+
+
[docs]defclear()->'XAColor':
+ """Initializes and returns a an :class:`XAColor` object whose alpha value is 0.0.
+
+ .. versionadded:: 0.1.0
+ """
+ returnXAColor(0,0,0,0)
+
+ @property
+ defred_value(self)->float:
+ """The red value of the color on the scale of 0.0 to 1.0.
+
+ .. versionadded:: 0.1.0
+ """
+ returnself.xa_elem.redComponent()
+
+ @red_value.setter
+ defred_value(self,red_value:float):
+ self.xa_elem=AppKit.NSCalibratedRGBColor.alloc().initWithRed_green_blue_alpha_(red_value,self.green_value,self.blue_value,self.alpha_value)
+
+ @property
+ defgreen_value(self)->float:
+ """The green value of the color on the scale of 0.0 to 1.0.
+
+ .. versionadded:: 0.1.0
+ """
+ returnself.xa_elem.greenComponent()
+
+ @green_value.setter
+ defgreen_value(self,green_value:float):
+ self.xa_elem=AppKit.NSCalibratedRGBColor.alloc().initWithRed_green_blue_alpha_(self.red_value,green_value,self.blue_value,self.alpha_value)
+
+ @property
+ defblue_value(self)->float:
+ """The blue value of the color on the scale of 0.0 to 1.0.
+
+ .. versionadded:: 0.1.0
+ """
+ returnself.xa_elem.blueComponent()
+
+ @blue_value.setter
+ defblue_value(self,blue_value:float):
+ self.xa_elem=AppKit.NSCalibratedRGBColor.alloc().initWithRed_green_blue_alpha_(self.red_value,self.green_value,blue_value,self.alpha_value)
+
+ @property
+ defalpha_value(self)->float:
+ """The alpha value of the color on the scale of 0.0 to 1.0.
+
+ .. versionadded:: 0.1.0
+ """
+ returnself.xa_elem.alphaComponent()
+
+ @alpha_value.setter
+ defalpha_value(self,alpha_value:float):
+ self.xa_elem=AppKit.NSCalibratedRGBColor.alloc().initWithRed_green_blue_alpha_(self.red_value,self.green_value,self.blue_value,alpha_value)
+
+ @property
+ defhue_value(self):
+ """The hue value of the color on the scale of 0.0 to 1.0.
+
+ .. versionadded:: 0.1.0
+ """
+ returnself.xa_elem.hueComponent()
+
+ @hue_value.setter
+ defhue_value(self,hue_value:float):
+ self.xa_elem=AppKit.NSCalibratedRGBColor.initWithHue_saturation_brightness_alpha_(hue_value,self.saturation_value,self.brightness_value,self.alpha_value)
+
+ @property
+ defsaturation_value(self):
+ """The staturation value of the color on the scale of 0.0 to 1.0.
+
+ .. versionadded:: 0.1.0
+ """
+ returnself.xa_elem.saturationComponent()
+
+ @saturation_value.setter
+ defsaturation_value(self,saturation_value:float):
+ self.xa_elem=AppKit.NSCalibratedRGBColor.initWithHue_saturation_brightness_alpha_(self.hue_value,saturation_value,self.brightness_value,self.alpha_value)
+
+ @property
+ defbrightness_value(self):
+ """The brightness value of the color on the scale of 0.0 to 1.0.
+
+ .. versionadded:: 0.1.0
+ """
+ returnself.xa_elem.brightnessComponent()
+
+ @brightness_value.setter
+ defbrightness_value(self,brightness_value:float):
+ self.xa_elem=AppKit.NSCalibratedRGBColor.initWithHue_saturation_brightness_alpha_(self.hue_value,self.saturation_value,brightness_value,self.alpha_value)
+
+
[docs]defcopy_color(self,color:AppKit.NSColor)->'XAColor':
+ """Initializes a XAColor copy of an NSColor object.
+
+ :param color: The NSColor to copy
+ :type color: AppKit.NSColor
+ :return: The newly created XAColor object
+ :rtype: XAColor
+
+ .. versionadded:: 0.1.0
+ """
+ self.xa_elem=AppKit.NSCalibratedRGBColor.alloc().initWithRed_green_blue_alpha_(
+ color.redComponent(),
+ color.greenComponent(),
+ color.blueComponent(),
+ color.alphaComponent()
+ )
+ returnself
+
+
[docs]defset_rgba(self,red:float,green:float,blue:float,alpha:float)->'XAColor':
+ """Sets the RGBA values of the color.
+
+ :param red: The red value of the color, from 0.0 to 1.0
+ :type red: float
+ :param green: The green value of the color, from 0.0 to 1.0
+ :type green: float
+ :param blue: The blue value of the color, from 0.0 to 1.0
+ :type blue: float
+ :param alpha: The opacity of the color, from 0.0 to 1.0
+ :type alpha: float
+ :return: The XAColor object
+ :rtype: XAColor
+
+ .. versionadded:: 0.1.0
+ """
+ self.xa_elem=AppKit.NSCalibratedRGBColor.alloc().initWithRed_green_blue_alpha_(red,green,blue,alpha)
+ returnself
+
+
[docs]defset_hsla(self,hue:float,saturation:float,brightness:float,alpha:float)->'XAColor':
+ """Sets the HSLA values of the color.
+
+ :param hue: The hue value of the color, from 0.0 to 1.0
+ :type hue: float
+ :param saturation: The saturation value of the color, from 0.0 to 1.0
+ :type saturation: float
+ :param brightness: The brightness value of the color, from 0.0 to 1.0
+ :type brightness: float
+ :param alpha: The opacity of the color, from 0.0 to 1.0
+ :type alpha: float
+ :return: The XAColor object
+ :rtype: XAColor
+
+ .. versionadded:: 0.1.0
+ """
+ self.xa_elem=AppKit.NSCalibratedRGBColor.initWithHue_saturation_brightness_alpha_(hue,saturation,brightness,alpha)
+ returnself
+
+
[docs]defmix_with(self,color:'XAColor',fraction:int=0.5)->'XAColor':
+ """Blends this color with the specified fraction of another.
+
+ :param color: The color to blend this color with
+ :type color: XAColor
+ :param fraction: The fraction of the other color to mix into this color, from 0.0 to 1.0, defaults to 0.5
+ :type fraction: int, optional
+ :return: The resulting color after mixing
+ :rtype: XAColor
+
+ .. versionadded:: 0.1.0
+ """
+ new_color=self.xa_elem.blendedColorWithFraction_ofColor_(fraction,color.xa_elem)
+ returnXAColor(new_color.redComponent(),new_color.greenComponent(),new_color.blueComponent(),new_color.alphaComponent())
+
+
[docs]defbrighten(self,fraction:float=0.5)->'XAColor':
+ """Brightens the color by mixing the specified fraction of the system white color into it.
+
+ :param fraction: The amount (fraction) of white to mix into the color, defaults to 0.5
+ :type fraction: float, optional
+ :return: The resulting color after brightening
+ :rtype: XAColor
+
+ .. versionadded:: 0.1.0
+ """
+ self.xa_elem=self.xa_elem.highlightWithLevel_(fraction)
+ returnself
+
+
[docs]defdarken(self,fraction:float=0.5)->'XAColor':
+ """Darkens the color by mixing the specified fraction of the system black color into it.
+
+ :param fraction: The amount (fraction) of black to mix into the color, defaults to 0.5
+ :type fraction: float, optional
+ :return: The resulting color after darkening
+ :rtype: XAColor
+
+ .. versionadded:: 0.1.0
+ """
+ self.xa_elem=self.xa_elem.shadowWithLevel_(fraction)
+ returnself
+
+
[docs]defmake_swatch(self,width:int=100,height:int=100)->'XAImage':
+ """Creates an image swatch of the color with the specified dimensions.
+
+ :param width: The width of the swatch image, in pixels, defaults to 100
+ :type width: int, optional
+ :param height: The height of the swatch image, in pixels, defaults to 100
+ :type height: int, optional
+ :return: The image swatch as an XAImage object
+ :rtype: XAImage
+
+ :Example: View swatches in Preview
+
+ >>> import PyXA
+ >>> from time import sleep
+ >>>
+ >>> blue = PyXA.XAColor.blue()
+ >>> red = PyXA.XAColor.red()
+ >>>
+ >>> swatches = [
+ >>> blue.make_swatch(),
+ >>> blue.darken(0.5).make_swatch(),
+ >>> blue.mix_with(red).make_swatch()
+ >>> ]
+ >>>
+ >>> for swatch in swatches:
+ >>> swatch.show_in_preview()
+ >>> sleep(0.2)
+
+ .. versionadded:: 0.1.0
+ """
+ img=AppKit.NSImage.alloc().initWithSize_(AppKit.NSMakeSize(width,height))
+ img.lockFocus()
+ self.xa_elem.drawSwatchInRect_(AppKit.NSMakeRect(0,0,width,height))
+ img.unlockFocus()
+ returnXAImage(img)
+
+
[docs]defget_clipboard_representation(self)->AppKit.NSColor:
+ """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.
+
+ :return: The raw color data
+ :rtype: AppKit.NSColor
+
+ .. versionadded:: 0.1.0
+ """
+ returnself.xa_elem
[docs]classXALocation(XAObject):
+ """A location with a latitude and longitude, along with other data.
+
+ .. versionadded:: 0.0.2
+ """
+ current_location:'XALocation'#: The current location of the device
+
+ def__init__(self,raw_value:CoreLocation.CLLocation=None,title:str=None,latitude:float=0,longitude:float=0,altitude:float=None,radius:int=0,address:str=None):
+ self.raw_value=raw_value#: The raw CLLocation object
+ self.title=title#: The name of the location
+ self.latitude=latitude#: The latitude of the location
+ self.longitude=longitude#: The longitude of the location
+ self.altitude=altitude#: The altitude of the location
+ self.radius=radius#: The horizontal accuracy of the location measurement
+ self.address=address#: The addres of the location
+
+ @property
+ defraw_value(self)->CoreLocation.CLLocation:
+ returnself.__raw_value
+
+ @raw_value.setter
+ defraw_value(self,raw_value:CoreLocation.CLLocation):
+ self.__raw_value=raw_value
+ ifraw_valueisnotNone:
+ self.latitude=raw_value.coordinate()[0]
+ self.longitude=raw_value.coordinate()[1]
+ self.altitude=raw_value.altitude()
+ self.radius=raw_value.horizontalAccuracy()
+
+ @property
+ defcurrent_location(self)->'XALocation':
+ self.raw_value=None
+ self._spawn_thread(self.__get_current_location)
+ whileself.raw_valueisNone:
+ time.sleep(0.01)
+ returnself
+
+
[docs]defshow_in_maps(self):
+ """Shows the location in Maps.app.
+
+ .. versionadded:: 0.0.6
+ """
+ XAURL(f"maps://?q={self.title},ll={self.latitude},{self.longitude}").open()
[docs]classXAAlertStyle(Enum):
+ """Options for which alert style an alert should display with.
+ """
+ INFORMATIONAL=AppKit.NSAlertStyleInformational
+ WARNING=AppKit.NSAlertStyleWarning
+ CRITICAL=AppKit.NSAlertStyleCritical
+
+
[docs]classXAAlert(XAObject):
+ """A class for creating and interacting with an alert dialog window.
+
+ .. versionadded:: 0.0.5
+ """
+ def__init__(self,title:str="Alert!",message:str="",style:XAAlertStyle=XAAlertStyle.INFORMATIONAL,buttons=["Ok","Cancel"]):
+ super().__init__()
+ self.title:str=title
+ self.message:str=message
+ self.style:XAAlertStyle=style
+ self.buttons:list[str]=buttons
+
+
[docs]defdisplay(self)->int:
+ """Displays the alert.
+
+ :return: A number representing the button that the user selected, if any
+ :rtype: int
+
+ .. versionadded:: 0.0.5
+ """
+ alert=AppKit.NSAlert.alloc().init()
+ alert.setMessageText_(self.title)
+ alert.setInformativeText_(self.message)
+ alert.setAlertStyle_(self.style.value)
+
+ forbuttoninself.buttons:
+ alert.addButtonWithTitle_(button)
+ returnalert.runModal()
+
+
+
+
+
[docs]classXAColorPickerStyle(Enum):
+ """Options for which tab a color picker should display when first opened.
+ """
+ GRAYSCALE=AppKit.NSColorPanelModeGray
+ RGB_SLIDERS=AppKit.NSColorPanelModeRGB
+ CMYK_SLIDERS=AppKit.NSColorPanelModeCMYK
+ HSB_SLIDERS=AppKit.NSColorPanelModeHSB
+ COLOR_LIST=AppKit.NSColorPanelModeColorList
+ COLOR_WHEEL=AppKit.NSColorPanelModeWheel
+ CRAYONS=AppKit.NSColorPanelModeCrayon
+ IMAGE_PALETTE=AppKit.NSColorPanelModeCustomPalette
+
+
[docs]classXAColorPicker(XAObject):
+ """A class for creating and interacting with a color picker window.
+
+ .. versionadded:: 0.0.5
+ """
+ def__init__(self,style:XAColorPickerStyle=XAColorPickerStyle.GRAYSCALE):
+ super().__init__()
+ self.style=style
+
+
[docs]defdisplay(self)->XAColor:
+ """Displays the color picker.
+
+ :return: The color that the user selected
+ :rtype: XAColor
+
+ .. versionadded:: 0.0.5
+ """
+ panel=AppKit.NSColorPanel.sharedColorPanel()
+ panel.setMode_(self.style.value)
+ panel.setShowsAlpha_(True)
+
+ defrun_modal(panel):
+ initial_color=panel.color()
+ time.sleep(0.5)
+ whilepanel.isVisible()andpanel.color()==initial_color:
+ time.sleep(0.01)
+ AppKit.NSApp.stopModal()
+
+ modal_thread=threading.Thread(target=run_modal,args=(panel,),name="Run Modal",daemon=True)
+ modal_thread.start()
+
+ AppKit.NSApp.runModalForWindow_(panel)
+ returnXAColor(panel.color())
[docs]defdisplay(self)->Union[str,int,None,list[str]]:
+ """Displays the dialog, waits for the user to select an option or cancel, then returns the selected button or None if cancelled.
+
+ :return: The selected button or None if no value was selected
+ :rtype: Union[str, int, None, list[str]]
+
+ .. versionadded:: 0.0.8
+ """
+ buttons=[x.replace("'","")forxinself.buttons]
+ buttons=str(buttons).replace("'",'"')
+
+ default_button=str(self.default_button).replace("'","")
+ default_button_str="default button \""+default_button+"\""ifself.default_buttonisnotNoneelse""
+
+ cancel_button=str(self.cancel_button).replace("'","")
+ cancel_button_str="cancel button \""+cancel_button+"\""ifself.cancel_buttonisnotNoneelse""
+
+ icon_str="with icon "+self.icon+""ifself.iconisnotNoneelse""
+
+ default_answer=str(self.default_answer).replace("'",'"')
+ default_answer_str="default answer \""+default_answer+"\""ifself.default_answerisnotNoneelse""
+
+ script=AppleScript(f"""
+ tell application "Terminal"
+ display dialog \"{self.text}\" with title \"{self.title}\" buttons {buttons}{default_button_str}{cancel_button_str}{icon_str}{default_answer_str} hidden answer {self.hidden_answer}
+ end tell
+ """)
+
+ result=script.run()["event"]
+ ifresultisnotNone:
+ ifresult.numberOfItems()>1:
+ return[result.descriptorAtIndex_(1).stringValue(),result.descriptorAtIndex_(2).stringValue()]
+ else:
+ returnresult.descriptorAtIndex_(1).stringValue()
+
+
+
+
+
[docs]classXAMenu(XAObject):
+ """A custom list item selection menu.
+
+ .. versionadded:: 0.0.8
+ """
+ def__init__(self,menu_items:list[Any],title:str="Select Item",prompt:str="Select an item",default_items:Union[list[str],None]=None,ok_button_name:str="Okay",cancel_button_name:str="Cancel",multiple_selections_allowed:bool=False,empty_selection_allowed:bool=False):
+ super().__init__()
+ self.menu_items:list[Union[str,int]]=menu_items#: The items the user can choose from
+ self.title:str=title#: The title of the dialog window
+ self.prompt:str=prompt#: The prompt to display in the dialog box
+ self.default_items:list[str]=default_itemsor[]#: The items to initially select
+ self.ok_button_name:str=ok_button_name#: The name of the OK button
+ self.cancel_button_name:str=cancel_button_name#: The name of the Cancel button
+ self.multiple_selections_allowed:bool=multiple_selections_allowed#: Whether multiple items can be selected
+ self.empty_selection_allowed:bool=empty_selection_allowed#: Whether the user can click OK without selecting anything
+
+
[docs]defdisplay(self)->Union[str,int,bool,list[str],list[int]]:
+ """Displays the menu, waits for the user to select an option or cancel, then returns the selected value or False if cancelled.
+
+ :return: The selected value or False if no value was selected
+ :rtype: Union[str, int, bool, list[str], list[int]]
+
+ .. versionadded:: 0.0.8
+ """
+ menu_items=[x.replace("'","")forxinself.menu_items]
+ menu_items=str(menu_items).replace("'",'"')
+ default_items=str(self.default_items).replace("'",'"')
+ script=AppleScript(f"""
+ tell application "Terminal"
+ choose from list {menu_items} with title \"{self.title}\" with prompt \"{self.prompt}\" default items {default_items} OK button name \"{self.ok_button_name}\" cancel button name \"{self.cancel_button_name}\" multiple selections allowed {self.multiple_selections_allowed} empty selection allowed {self.empty_selection_allowed}
+ end tell
+ """)
+ result=script.run()["event"]
+ ifresultisnotNone:
+ ifself.multiple_selections_allowed:
+ values=[]
+ forxinrange(1,result.numberOfItems()+1):
+ desc=result.descriptorAtIndex_(x)
+ values.append(desc.stringValue())
+ returnvalues
+ else:
+ ifresult.stringValue()=="false":
+ returnFalse
+ returnresult.stringValue()
+
+
+
+
+
[docs]classXAFilePicker(XAObject):
+ """A file selection window.
+
+ .. versionadded:: 0.0.8
+ """
+ def__init__(self,prompt:str="Choose File",types:list[str]=None,default_location:Union[str,None]=None,show_invisibles:bool=False,multiple_selections_allowed:bool=False,show_package_contents:bool=False):
+ super().__init__()
+ self.prompt:str=prompt#: The prompt to display in the dialog box
+ self.types:list[str]=types#: The file types/type identifiers to allow for selection
+ self.default_location:Union[str,None]=default_location#: The default file location
+ self.show_invisibles:bool=show_invisibles#: Whether invisible files and folders are shown
+ self.multiple_selections_allowed:bool=multiple_selections_allowed#: Whether the user can select multiple files
+ self.show_package_contents:bool=show_package_contents#: Whether to show the contents of packages
+
+
[docs]defdisplay(self)->Union[XAPath,None]:
+ """Displays the file chooser, waits for the user to select a file or cancel, then returns the selected file URL or None if cancelled.
+
+ :return: The selected file URL or None if no file was selected
+ :rtype: Union[XAPath, None]
+
+ .. versionadded:: 0.0.8
+ """
+ types=[x.replace("'","")forxinself.types]
+ types=str(types).replace("'",'"')
+ types_str="of type "+typesifself.typesisnotNoneelse""
+
+ default_location_str="default location \""+self.default_location+"\""ifself.default_locationisnotNoneelse""
+
+ script=AppleScript(f"""
+ tell application "Terminal"
+ choose file with prompt \"{self.prompt}\"{types_str}{default_location_str} invisibles {self.show_invisibles} multiple selections allowed {self.multiple_selections_allowed} showing package contents {self.show_package_contents}
+ end tell
+ """)
+ result=script.run()["event"]
+
+ ifresultisnotNone:
+ ifself.multiple_selections_allowed:
+ values=[]
+ forxinrange(1,result.numberOfItems()+1):
+ desc=result.descriptorAtIndex_(x)
+ values.append(XAPath(desc.fileURLValue()))
+ returnvalues
+ else:
+ returnXAPath(result.fileURLValue())
+
+
+
+
+
[docs]classXAFolderPicker(XAObject):
+ """A folder selection window.
+
+ .. versionadded:: 0.0.8
+ """
+ def__init__(self,prompt:str="Choose Folder",default_location:Union[str,None]=None,show_invisibles:bool=False,multiple_selections_allowed:bool=False,show_package_contents:bool=False):
+ super().__init__()
+ self.prompt:str=prompt#: The prompt to display in the dialog box
+ self.default_location:Union[str,None]=default_location#: The default folder location
+ self.show_invisibles:bool=show_invisibles#: Whether invisible files and folders are shown
+ self.multiple_selections_allowed:bool=multiple_selections_allowed#: Whether the user can select multiple folders
+ self.show_package_contents:bool=show_package_contents#: Whether to show the contents of packages
+
+
[docs]defdisplay(self)->Union[XAPath,None]:
+ """Displays the folder chooser, waits for the user to select a folder or cancel, then returns the selected folder URL or None if cancelled.
+
+ :return: The selected folder URL or None if no folder was selected
+ :rtype: Union[XAPath, None]
+
+ .. versionadded:: 0.0.8
+ """
+
+ default_location_str="default location \""+self.default_location+"\""ifself.default_locationisnotNoneelse""
+
+ script=AppleScript(f"""
+ tell application "Terminal"
+ choose folder with prompt \"{self.prompt}\"{default_location_str} invisibles {self.show_invisibles} multiple selections allowed {self.multiple_selections_allowed} showing package contents {self.show_package_contents}
+ end tell
+ """)
+ result=script.run()["event"]
+ ifresultisnotNone:
+ ifself.multiple_selections_allowed:
+ values=[]
+ forxinrange(1,result.numberOfItems()+1):
+ desc=result.descriptorAtIndex_(x)
+ values.append(XAPath(desc.fileURLValue()))
+ returnvalues
+ else:
+ returnXAPath(result.fileURLValue())
+
+
+
+
+
[docs]classXAApplicationPicker(XAObject):
+ """An application selection window.
+
+ .. versionadded:: 0.1.0
+ """
+ def__init__(self,title:Union[str,None]=None,prompt:Union[str,None]=None,multiple_selections_allowed:bool=False):
+ super().__init__()
+ self.title:str=title#: The dialog window title
+ self.prompt:str=prompt#: The prompt to be displayed in the dialog box
+ self.multiple_selections_allowed:bool=multiple_selections_allowed#: Whether to allow multiple items to be selected
+
+
[docs]defdisplay(self)->str:
+ """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.
+
+ :return: The name of the selected application
+ :rtype: str
+
+ .. versionadded:: 0.0.8
+ """
+
+ script=AppleScript("tell application \"Terminal\"")
+ dialog_str="choose application "
+ ifself.titleisnotNone:
+ dialog_str+=f"with title \"{self.title}\" "
+ ifself.promptisnotNone:
+ dialog_str+=f"with prompt \"{self.prompt}\""
+ dialog_str+=f"multiple selections allowed {self.multiple_selections_allowed} "
+ script.add(dialog_str)
+ script.add("end tell")
+
+ returnscript.run()["string"]
+
+
+
+
+
[docs]classXAFileNameDialog(XAObject):
+ """A file name input window.
+
+ .. versionadded:: 0.0.8
+ """
+ def__init__(self,prompt:str="Specify file name and location",default_name:str="New File",default_location:Union[str,None]=None):
+ super().__init__()
+ self.prompt:str=prompt#: The prompt to display in the dialog box
+ self.default_name:str=default_name#: The default name for the new file
+ self.default_location:Union[str,None]=default_location#: The default file location
+
+
[docs]defdisplay(self)->Union[XAPath,None]:
+ """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.
+
+ :return: The specified file URL or None if no file name was inputted
+ :rtype: Union[XAPath, None]
+
+ .. versionadded:: 0.0.8
+ """
+
+ default_location_str="default location \""+self.default_location+"\""ifself.default_locationisnotNoneelse""
+
+ script=AppleScript(f"""
+ tell application "Terminal"
+ choose file name with prompt \"{self.prompt}\" default name \"{self.default_name}\"{default_location_str}
+ end tell
+ """)
+ result=script.run()["event"]
+ ifresultisnotNone:
+ returnXAPath(result.fileURLValue())
+
+
+
+
+
[docs]classXAMenuBar(XAObject):
+ def__init__(self):
+ """Creates a new menu bar object for interacting with the system menu bar.
+
+ .. versionadded:: 0.0.9
+ """
+ self._menus={}
+ self._menu_items={}
+ self._methods={}
+
+ detector=self
+ classMyApplicationAppDelegate(AppKit.NSObject):
+ start_time=datetime.now()
+
+ defapplicationDidFinishLaunching_(self,sender):
+ foritem_name,status_itemindetector._menus.items():
+ menu=status_item.menu()
+
+ menuitem=AppKit.NSMenuItem.alloc().initWithTitle_action_keyEquivalent_('Quit','terminate:','')
+ menu.addItem_(menuitem)
+
+ defaction_(self,menu_item):
+ selection=menu_item.title()
+ foritem_nameindetector._methods:
+ ifselection==item_name:
+ detector._methods[item_name]()
+
+ app=AppKit.NSApplication.sharedApplication()
+ app.setDelegate_(MyApplicationAppDelegate.alloc().init().retain())
+
+
[docs]defadd_menu(self,title:str,image:Union['XAImage',None]=None,tool_tip:Union[str,None]=None,img_width:int=30,img_height:int=30):
+ """Adds a new menu to be displayed in the system menu bar.
+
+ :param title: The name of the menu
+ :type title: str
+ :param image: The image to display for the menu, defaults to None
+ :type image: Union[XAImage, None], optional
+ :param tool_tip: The tooltip to display on hovering over the menu, defaults to None
+ :type tool_tip: Union[str, None], optional
+ :param img_width: The width of the image, in pixels, defaults to 30
+ :type img_width: int, optional
+ :param img_height: The height of the image, in pixels, defaults to 30
+ :type img_height: int, optional
+
+ :Example:
+
+ >>> import PyXA
+ >>> menu_bar = PyXA.XAMenuBar()
+ >>> img = PyXA.XAImage("/Users/steven/Downloads/Blackness.jpg")
+ >>> menu_bar.add_menu("Menu 1", image=img, img_width=100, img_height=100)
+ >>> menu_bar.display()
+
+ .. versionadded:: 0.0.9
+ """
+ status_bar=AppKit.NSStatusBar.systemStatusBar()
+ status_item=status_bar.statusItemWithLength_(AppKit.NSVariableStatusItemLength).retain()
+ status_item.setTitle_(title)
+
+ ifisinstance(image,XAImage):
+ img=image.xa_elem.copy()
+ img.setScalesWhenResized_(True)
+ img.setSize_((img_width,img_height))
+ status_item.button().setImage_(img)
+
+ status_item.setHighlightMode_(objc.YES)
+
+ ifisinstance(tool_tip,str):
+ status_item.setToolTip_(tool_tip)
+
+ menu=AppKit.NSMenu.alloc().init()
+ status_item.setMenu_(menu)
+
+ status_item.setEnabled_(objc.YES)
+ self._menus[title]=status_item
+
+
[docs]defadd_item(self,menu:str,item_name:str,method:Union[Callable[[],None],None]=None,image:Union['XAImage',None]=None,img_width:int=20,img_height:int=20):
+ """Adds an item to a menu, creating the menu if necessary.
+
+ :param menu: The name of the menu to add an item to, or the name of the menu to create
+ :type menu: str
+ :param item_name: The name of the item
+ :type item_name: str
+ :param method: The method to associate with the item (the method called when the item is clicked)
+ :type method: Callable[[], None]
+ :param image: The image for the item, defaults to None
+ :type image: Union[XAImage, None], optional
+ :param img_width: The width of image, in pixels, defaults to 30
+ :type img_width: int, optional
+ :param img_height: The height of the image, in pixels, defaults to 30
+ :type img_height: int, optional
+
+ :Example:
+
+ >>> import PyXA
+ >>> menu_bar = PyXA.XAMenuBar()
+ >>>
+ >>> menu_bar.add_menu("Menu 1")
+ >>> menu_bar.add_item(menu="Menu 1", item_name="Item 1", method=lambda : print("Action 1"))
+ >>> menu_bar.add_item(menu="Menu 1", item_name="Item 2", method=lambda : print("Action 2"))
+ >>>
+ >>> menu_bar.add_item(menu="Menu 2", item_name="Item 1", method=lambda : print("Action 1"))
+ >>> img = PyXA.XAImage("/Users/exampleUser/Downloads/example.jpg")
+ >>> menu_bar.add_item("Menu 2", "Item 1", lambda : print("Action 1"), image=img, img_width=100)
+ >>> menu_bar.display()
+
+ .. versionadded:: 0.0.9
+ """
+ item=AppKit.NSMenuItem.alloc().initWithTitle_action_keyEquivalent_(item_name,'action:','')
+
+ ifisinstance(image,XAImage):
+ img=image.xa_elem.copy()
+ img.setScalesWhenResized_(True)
+ img.setSize_((img_width,img_height))
+ item.setImage_(img)
+
+ ifmenunotinself._menus:
+ self.add_menu(menu)
+ self._menu_items[item_name]=item
+ self._menus[menu].menu().addItem_(item)
+ self._methods[item_name]=method
+
+
[docs]defset_image(self,item_name:str,image:'XAImage',img_width:int=30,img_height:int=30):
+ """Sets the image displayed for a menu or menu item.
+
+ :param item_name: The name of the item to update
+ :type item_name: str
+ :param image: The image to display
+ :type image: XAImage
+ :param img_width: The width of the image, in pixels, defaults to 30
+ :type img_width: int, optional
+ :param img_height: The height of the image, in pixels, defaults to 30
+ :type img_height: int, optional
+
+ :Example: Set Image on State Change
+
+ >>> import PyXA
+ >>> current_state = True # On
+ >>> img_on = PyXA.XAImage("/Users/exampleUser/Documents/on.jpg")
+ >>> img_off = PyXA.XAImage("/Users/exampleUser/Documents/off.jpg")
+ >>> menu_bar = PyXA.XAMenuBar()
+ >>> menu_bar.add_menu("Status", image=img_on)
+ >>>
+ >>> def update_state():
+ >>> global current_state
+ >>> if current_state is True:
+ >>> # ... (Actions for turning off)
+ >>> menu_bar.set_text("Turn off", "Turn on")
+ >>> menu_bar.set_image("Status", img_off)
+ >>> current_state = False
+ >>> else:
+ >>> # ... (Actions for turning on)
+ >>> menu_bar.set_text("Turn off", "Turn off")
+ >>> menu_bar.set_image("Status", img_on)
+ >>> current_state = True
+
+ menu_bar.add_item("Status", "Turn off", update_state)
+ menu_bar.display()
+
+ .. versionadded:: 0.0.9
+ """
+ img=image.xa_elem.copy()
+ img.setScalesWhenResized_(True)
+ img.setSize_((img_width,img_height))
+ ifitem_nameinself._menus:
+ self._menus[item_name].button().setImage_(img)
+ elifitem_nameinself._methods:
+ self._menu_items[item_name].setImage_(img)
+
+
[docs]defset_text(self,item_name:str,text:str):
+ """Sets the text displayed for a menu or menu item.
+
+ :param item_name: The name of the item to update
+ :type item_name: str
+ :param text: The new text to display
+ :type text: str
+
+ :Example: Random Emoji Ticker
+
+ >>> import PyXA
+ >>> import random
+ >>> import threading
+ >>>
+ >>> menu_bar = PyXA.XAMenuBar()
+ >>> menu_bar.add_menu("Emoji")
+ >>>
+ >>> emojis = ["😀", "😍", "🙂", "😎", "🤩", "🤯", "😭", "😱", "😴", "🤒", "😈", "🤠"]
+ >>>
+ >>> def update_display():
+ >>> while True:
+ >>> new_emoji = random.choice(emojis)
+ >>> menu_bar.set_text("Emoji", new_emoji)
+ >>> sleep(0.25)
+ >>>
+ >>> emoji_ticker = threading.Thread(target=update_display)
+ >>> emoji_ticker.start()
+ >>> menu_bar.display()
+
+ .. versionadded:: 0.0.9
+ """
+ ifitem_nameinself._menus:
+ self._menus[item_name].setTitle_(text)
+ elifitem_nameinself._methods:
+ self._menu_items[item_name].setTitle_(text)
+ self._methods[text]=self._methods[item_name]
+
+
[docs]defdisplay(self):
+ """Displays the custom menus on the menu bar.
+
+ :Example:
+
+ >>> import PyXA
+ >>> mbar = PyXA.XAMenuBar()
+ >>> mbar.add_menu("🔥")
+ >>> mbar.display()
+
+ .. versionadded:: 0.0.9
+ """
+ try:
+ AppHelper.runEventLoop(installInterrupt=True)
+ exceptExceptionase:
+ print(e)
+
+
+
+
+#############################
+### System / Image Events ###
+#############################
+# ? Move into separate XAFileSystemBase.py file?
+
[docs]classXAEventsApplication(XACanOpenPath):
+ """A base class for the System and Image events applications.
+
+ .. versionadded:: 0.1.0
+ """
+
[docs]classXADiskItemList(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.
+
+ .. versionadded:: 0.1.0
+ """
+ def__init__(self,properties:dict,filter:Union[dict,None]=None,object_class=None):
+ ifobject_classisNone:
+ object_class=XADiskItem
+ super().__init__(properties,object_class,filter)
+
+
[docs]defbusy_status(self)->list['bool']:
+ """Retrieves the busy status of each disk item in the list.
+
+ .. versionadded:: 0.1.0
+ """
+ returnlist(self.xa_elem.arrayByApplyingSelector_("busyStatus"))
+
+
[docs]defcontainer(self)->'XADiskItemList':
+ """Retrieves the containing folder or disk of each disk item in the list.
+
+ .. versionadded:: 0.1.0
+ """
+ ls=self.xa_elem.arrayByApplyingSelector_("container")
+ returnself._new_element(ls,XADiskItemList)
+
+
[docs]defcreation_date(self)->list['datetime']:
+ """Retrieves the creation date of each disk item in the list.
+
+ .. versionadded:: 0.1.0
+ """
+ returnlist(self.xa_elem.arrayByApplyingSelector_("creationDate"))
+
+
[docs]defdisplayed_name(self)->list['str']:
+ """Retrieves the displayed name of each disk item in the list.
+
+ .. versionadded:: 0.1.0
+ """
+ returnlist(self.xa_elem.arrayByApplyingSelector_("displayedName"))
+
+
[docs]defid(self)->list['str']:
+ """Retrieves the unique ID of each disk item in the list.
+
+ .. versionadded:: 0.1.0
+ """
+ returnlist(self.xa_elem.arrayByApplyingSelector_("id"))
+
+
[docs]defmodification_date(self)->list['datetime']:
+ """Retrieves the last modified date of each disk item in the list.
+
+ .. versionadded:: 0.1.0
+ """
+ returnlist(self.xa_elem.arrayByApplyingSelector_("modificationDate"))
+
+
[docs]defname(self)->list['str']:
+ """Retrieves the name of each disk item in the list.
+
+ .. versionadded:: 0.1.0
+ """
+ returnlist(self.xa_elem.arrayByApplyingSelector_("name"))
+
+
[docs]defname_extension(self)->list['str']:
+ """Retrieves the name extension of each disk item in the list.
+
+ .. versionadded:: 0.1.0
+ """
+ returnlist(self.xa_elem.arrayByApplyingSelector_("nameExtension"))
+
+
[docs]defpackage_folder(self)->list['bool']:
+ """Retrieves the package folder status of each disk item in the list.
+
+ .. versionadded:: 0.1.0
+ """
+ returnlist(self.xa_elem.arrayByApplyingSelector_("packageFolder"))
+
+
[docs]defpath(self)->list['XAPath']:
+ """Retrieves the file system path of each disk item in the list.
+
+ .. versionadded:: 0.1.0
+ """
+ ls=self.xa_elem.arrayByApplyingSelector_("path")
+ return[XAPath(x)forxinls]
+
+
[docs]defphysical_size(self)->list['int']:
+ """Retrieves the actual disk space used by each disk item in the list.
+
+ .. versionadded:: 0.1.0
+ """
+ returnlist(self.xa_elem.arrayByApplyingSelector_("physicalSize"))
+
+
[docs]defposix_path(self)->list[XAPath]:
+ """Retrieves the POSIX file system path of each disk item in the list.
+
+ .. versionadded:: 0.1.0
+ """
+ ls=self.xa_elem.arrayByApplyingSelector_("POSIXPath")
+ return[XAPath(x)forxinls]
+
+
[docs]defsize(self)->list['int']:
+ """Retrieves the logical size of each disk item in the list.
+
+ .. versionadded:: 0.1.0
+ """
+ returnlist(self.xa_elem.arrayByApplyingSelector_("size"))
+
+
[docs]defurl(self)->list['XAURL']:
+ """Retrieves the URL of each disk item in the list.
+
+ .. versionadded:: 0.1.0
+ """
+ ls=self.xa_elem.arrayByApplyingSelector_("URL")
+ return[XAURL(x)forxinls]
+
+
[docs]defvisible(self)->list['bool']:
+ """Retrieves the visible status of each item in the list.
+
+ .. versionadded:: 0.1.0
+ """
+ returnlist(self.xa_elem.arrayByApplyingSelector_("visible"))
+
+
[docs]defvolume(self)->list['str']:
+ """Retrieves the volume on which each item in the list resides.
+
+ .. versionadded:: 0.1.0
+ """
+ returnlist(self.xa_elem.arrayByApplyingSelector_("volume"))
+
+
[docs]defby_busy_status(self,busy_status:bool)->'XADiskItem':
+ """Retrieves item whose busy status matches the given boolean value.
+
+ .. versionadded:: 0.1.0
+ """
+ returnself.by_property("busyStatus",busy_status)
+
+
[docs]defby_container(self,container:'XADiskItem')->'XADiskItem':
+ """Retrieves item whose container matches the given disk item.
+
+ .. versionadded:: 0.1.0
+ """
+ returnself.by_property("container",container.xa_elem)
+
+
[docs]defby_creation_date(self,creation_date:datetime)->'XADiskItem':
+ """Retrieves item whose creation date matches the given date.
+
+ .. versionadded:: 0.1.0
+ """
+ returnself.by_property("creationDate",creation_date)
+
+
[docs]defby_displayed_name(self,displayed_name:str)->'XADiskItem':
+ """Retrieves item whose displayed name matches the given name.
+
+ .. versionadded:: 0.1.0
+ """
+ returnself.by_property("displayedName",displayed_name)
+
+
[docs]defby_id(self,id:str)->'XADiskItem':
+ """Retrieves item whose ID matches the given ID.
+
+ .. versionadded:: 0.1.0
+ """
+ returnself.by_property("id",id)
+
+
[docs]defby_modification_date(self,modification_date:datetime)->'XADiskItem':
+ """Retrieves item whose date matches the given date.
+
+ .. versionadded:: 0.1.0
+ """
+ returnself.by_property("modificationDate",modification_date)
+
+
[docs]defby_name(self,name:str)->'XADiskItem':
+ """Retrieves item whose name matches the given name.
+
+ .. versionadded:: 0.1.0
+ """
+ returnself.by_property("name",name)
+
+
[docs]defby_name_extension(self,name_extension:str)->'XADiskItem':
+ """Retrieves item whose name extension matches the given extension.
+
+ .. versionadded:: 0.1.0
+ """
+ returnself.by_property("nameExtension",name_extension)
+
+
[docs]defby_package_folder(self,package_folder:bool)->'XADiskItem':
+ """Retrieves item whose package folder status matches the given boolean value.
+
+ .. versionadded:: 0.1.0
+ """
+ returnself.by_property("packageFolder",package_folder)
[docs]classXAAliasList(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.
+
+ .. versionadded:: 0.1.0
+ """
+ def__init__(self,properties:dict,filter:Union[dict,None]=None):
+ super().__init__(properties,filter,XAAlias)
+
+
[docs]defcreator_type(self)->list['str']:
+ """Retrieves the OSType identifying the application that created each alias in the list
+
+ .. versionadded:: 0.1.0
+ """
+ returnlist(self.xa_elem.arrayByApplyingSelector_("creatorType"))
+
+
[docs]defdefault_application(self)->'XADiskItemList':
+ """Retrieves the applications that will launch if each alias in the list is opened.
+
+ .. versionadded:: 0.1.0
+ """
+ ls=self.xa_elem.arrayByApplyingSelector_("defaultApplication")
+ returnself._new_element(ls,XADiskItemList)
+
+
[docs]deffile_type(self)->list['str']:
+ """Retrieves the OSType identifying the type of data contained in each alias in the list.
+
+ .. versionadded:: 0.1.0
+ """
+ returnlist(self.xa_elem.arrayByApplyingSelector_("fileType"))
+
+
[docs]defkind(self)->list['str']:
+ """Retrieves the kind of each alias in the list.
+
+ .. versionadded:: 0.1.0
+ """
+ returnlist(self.xa_elem.arrayByApplyingSelector_("kind"))
+
+
[docs]defproduct_version(self)->list['str']:
+ """Retrieves the product version of each alias in the list.
+
+ .. versionadded:: 0.1.0
+ """
+ returnlist(self.xa_elem.arrayByApplyingSelector_("productVersion"))
+
+
[docs]defshort_version(self)->list['str']:
+ """Retrieves the short version of the application bundle referenced by each alias in the list.
+
+ .. versionadded:: 0.1.0
+ """
+ returnlist(self.xa_elem.arrayByApplyingSelector_("shortVersion"))
+
+
[docs]defstationery(self)->list['bool']:
+ """Retrieves the stationery status of each alias in the list.
+
+ .. versionadded:: 0.1.0
+ """
+ returnlist(self.xa_elem.arrayByApplyingSelector_("stationery"))
+
+
[docs]deftype_identifier(self)->list['str']:
+ """Retrieves the type identifier of each alias in the list.
+
+ .. versionadded:: 0.1.0
+ """
+ returnlist(self.xa_elem.arrayByApplyingSelector_("typeIdentifier"))
+
+
[docs]defversion(self)->list['str']:
+ """Retrieves the version of the application bundle referenced by each alias in the list.
+
+ .. versionadded:: 0.1.0
+ """
+ returnlist(self.xa_elem.arrayByApplyingSelector_("version"))
+
+
[docs]defby_creator_type(self,creator_type:str)->'XAAlias':
+ """Retrieves the alias whose creator type matches the given creator type.
+
+ .. versionadded:: 0.1.0
+ """
+ returnself.by_property("creatorType",creator_type)
+
+
[docs]defby_default_application(self,default_application:'XADiskItem')->'XAAlias':
+ """Retrieves the alias whose default application matches the given application.
+
+ .. versionadded:: 0.1.0
+ """
+ returnself.by_property("defaultApplication",default_application.xa_elem)
+
+
[docs]defby_file_type(self,file_type:str)->'XAAlias':
+ """Retrieves the alias whose file type matches the given file type.
+
+ .. versionadded:: 0.1.0
+ """
+ returnself.by_property("fileType",file_type)
+
+
[docs]defby_kind(self,kind:str)->'XAAlias':
+ """Retrieves the alias whose kind matches the given kind.
+
+ .. versionadded:: 0.1.0
+ """
+ returnself.by_property("kind",kind)
+
+
[docs]defby_product_version(self,product_version:str)->'XAAlias':
+ """Retrieves the alias whose product version matches the given version.
+
+ .. versionadded:: 0.1.0
+ """
+ returnself.by_property("productVersion",product_version)
+
+
[docs]defby_short_version(self,short_version:str)->'XAAlias':
+ """Retrieves the alias whose short version matches the given text.
+
+ .. versionadded:: 0.1.0
+ """
+ returnself.by_property("shortVersion",short_version)
+
+
[docs]defby_stationery(self,stationery:bool)->'XAAlias':
+ """Retrieves the alias whose stationery status matches the given boolean value.
+
+ .. versionadded:: 0.1.0
+ """
+ returnself.by_property("stationery",stationery)
+
+
[docs]defby_type_identifier(self,type_identifier:str)->'XAAlias':
+ """Retrieves the alias whose type identifier matches the given type identifier.
+
+ .. versionadded:: 0.1.0
+ """
+ returnself.by_property("typeIdentifier",type_identifier)
+
+
[docs]defby_version(self,version:str)->'XAAlias':
+ """Retrieves the alias whose version matches the given version.
+
+ .. versionadded:: 0.1.0
+ """
+ returnself.by_property("version",version)
+
+
[docs]classXAAlias(XADiskItem):
+ """An alias in the file system.
+
+ .. versionadded:: 0.1.0
+ """
+ def__init__(self,properties):
+ super().__init__(properties)
+
+ @property
+ defcreator_type(self)->'str':
+ """The OSType identifying the application that created the alias.
+
+ .. versionadded:: 0.1.0
+ """
+ returnself.xa_elem.creatorType()
+
+ @property
+ defdefault_application(self)->'XADiskItem':
+ """The application that will launch if the alias is opened.
+
+ .. versionadded:: 0.1.0
+ """
+ returnself._new_element(self.xa_elem.defaultApplication(),XADiskItem)
+
+ @property
+ deffile_type(self)->'str':
+ """The OSType identifying the type of data contained in the alias.
+
+ .. versionadded:: 0.1.0
+ """
+ returnself.xa_elem.fileType()
+
+ @property
+ defkind(self)->'str':
+ """The kind of alias, as shown in Finder.
+
+ .. versionadded:: 0.1.0
+ """
+ returnself.xa_elem.kind()
+
+ @property
+ defproduct_version(self)->'str':
+ """The version of the product (visible at the top of the "Get Info" window).
+
+ .. versionadded:: 0.1.0
+ """
+ returnself.xa_elem.productVersion()
+
+ @property
+ defshort_version(self)->'str':
+ """The short version of the application bundle referenced by the alias.
+
+ .. versionadded:: 0.1.0
+ """
+ returnself.xa_elem.shortVersion()
+
+ @property
+ defstationery(self)->'bool':
+ """Whether the alias is a stationery pad.
+
+ .. versionadded:: 0.1.0
+ """
+ returnself.xa_elem.stationery()
+
+ @property
+ deftype_identifier(self)->'str':
+ """The type identifier of the alias.
+
+ .. versionadded:: 0.1.0
+ """
+ returnself.xa_elem.typeIdentifier()
+
+ @property
+ defversion(self)->'str':
+ """The version of the application bundle referenced by the alias (visible at the bottom of the "Get Info" window).
+
+ .. versionadded:: 0.1.0
+ """
+ returnself.xa_elem.version()
+
+
[docs]defaliases(self,filter:Union[dict,None]=None)->'XAAliasList':
+ """Returns a list of aliases, as PyXA objects, matching the given filter.
+
+ .. versionadded:: 0.1.0
+ """
+ self._new_element(self.xa_elem.aliases(),XAAliasList,filter)
+
+
[docs]defdisk_items(self,filter:Union[dict,None]=None)->'XADiskItemList':
+ """Returns a list of disk items, as PyXA objects, matching the given filter.
+
+ .. versionadded:: 0.1.0
+ """
+ self._new_element(self.xa_elem.diskItems(),XADiskItemList,filter)
+
+
[docs]deffiles(self,filter:Union[dict,None]=None)->'XAFileList':
+ """Returns a list of files, as PyXA objects, matching the given filter.
+
+ .. versionadded:: 0.1.0
+ """
+ self._new_element(self.xa_elem.files(),XAFileList,filter)
+
+
[docs]deffile_packages(self,filter:Union[dict,None]=None)->'XAFilePackageList':
+ """Returns a list of file packages, as PyXA objects, matching the given filter.
+
+ .. versionadded:: 0.1.0
+ """
+ self._new_element(self.xa_elem.filePackages(),XAFilePackageList,filter)
+
+
[docs]deffolders(self,filter:Union[dict,None]=None)->'XAFolderList':
+ """Returns a list of folders, as PyXA objects, matching the given filter.
+
+ .. versionadded:: 0.1.0
+ """
+ self._new_element(self.xa_elem.folders(),XAFolderList,filter)
+
+
+
+
+
[docs]classXADiskList(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.
+
+ .. versionadded:: 0.1.0
+ """
+ def__init__(self,properties:dict,filter:Union[dict,None]=None):
+ super().__init__(properties,filter,XADisk)
+
+
[docs]defcapacity(self)->list['float']:
+ """Retrieves the total number of bytes (free or used) on each disk in the list.
+
+ .. versionadded:: 0.1.0
+ """
+ returnlist(self.xa_elem.arrayByApplyingSelector_("capacity"))
+
+
[docs]defejectable(self)->list['bool']:
+ """Retrieves the ejectable status of each disk in the list.
+
+ .. versionadded:: 0.1.0
+ """
+ returnlist(self.xa_elem.arrayByApplyingSelector_("ejectable"))
+
+
[docs]defformat(self)->list['XAEventsApplication.Format']:
+ """Retrieves the file system format of each disk in the list.
+
+ .. versionadded:: 0.1.0
+ """
+ ls=self.xa_elem.arrayByApplyingSelector_("format")
+ return[XAEventsApplication.Format(OSType(x.stringValue()))forxinls]
+
+
[docs]deffree_space(self)->list['float']:
+ """Retrieves the number of free bytes left on each disk in the list.
+
+ .. versionadded:: 0.1.0
+ """
+ returnlist(self.xa_elem.arrayByApplyingSelector_("freeSpace"))
+
+
[docs]defignore_privileges(self)->list['bool']:
+ """Retrieves the ignore privileges status for each disk in the list.
+
+ .. versionadded:: 0.1.0
+ """
+ returnlist(self.xa_elem.arrayByApplyingSelector_("ignorePrivileges"))
+
+
[docs]deflocal_volume(self)->list['bool']:
+ """Retrieves the local volume status for each disk in the list.
+
+ .. versionadded:: 0.1.0
+ """
+ returnlist(self.xa_elem.arrayByApplyingSelector_("localVolume"))
+
+
[docs]defserver(self)->list['str']:
+ """Retrieves the server on which each disk in the list resides, AFP volumes only.
+
+ .. versionadded:: 0.1.0
+ """
+ returnlist(self.xa_elem.arrayByApplyingSelector_("server"))
+
+
[docs]defstartup(self)->list['bool']:
+ """Retrieves the startup disk status of each disk in the list.
+
+ .. versionadded:: 0.1.0
+ """
+ returnlist(self.xa_elem.arrayByApplyingSelector_("startup"))
+
+
[docs]defzone(self)->list['str']:
+ """Retrieves the zone in which each disk's server resides, AFP volumes only.
+
+ .. versionadded:: 0.1.0
+ """
+ returnlist(self.xa_elem.arrayByApplyingSelector_("zone"))
+
+
[docs]defby_capacity(self,capacity:float)->'XADisk':
+ """Retrieves the disk whose capacity matches the given capacity.
+
+ .. versionadded:: 0.1.0
+ """
+ returnself.by_property("capacity",capacity)
+
+
[docs]defby_ejectable(self,ejectable:bool)->'XADisk':
+ """Retrieves the disk whose ejectable status matches the given boolean value.
+
+ .. versionadded:: 0.1.0
+ """
+ returnself.by_property("ejectable",ejectable)
+
+
[docs]defby_format(self,format:'XAEventsApplication.Format')->'XADisk':
+ """Retrieves the disk whose format matches the given format.
+
+ .. versionadded:: 0.1.0
+ """
+ returnself.by_property("format",format.value)
+
+
[docs]defby_free_space(self,free_space:float)->'XADisk':
+ """Retrieves the disk whose free space matches the given amount.
+
+ .. versionadded:: 0.1.0
+ """
+ returnself.by_property("freeSpace",free_space)
+
+
[docs]defby_ignore_privileges(self,ignore_privileges:bool)->'XADisk':
+ """Retrieves the disk whose ignore privileges status matches the given boolean value.
+
+ .. versionadded:: 0.1.0
+ """
+ returnself.by_property("ignorePrivileges",ignore_privileges)
+
+
[docs]defby_local_volume(self,local_volume:bool)->'XADisk':
+ """Retrieves the disk whose local volume status matches the given boolean value.
+
+ .. versionadded:: 0.1.0
+ """
+ returnself.by_property("localVolume",local_volume)
+
+
[docs]defby_server(self,server:str)->'XADisk':
+ """Retrieves the disk whose server matches the given server.
+
+ .. versionadded:: 0.1.0
+ """
+ returnself.by_property("server",server)
+
+
[docs]defby_startup(self,startup:bool)->'XADisk':
+ """Retrieves the disk whose startup status matches the given boolean value.
+
+ .. versionadded:: 0.1.0
+ """
+ returnself.by_property("startup",startup)
+
+
[docs]defby_zone(self,zone:str)->'XADisk':
+ """Retrieves the disk whose zone matches the given zone.
+
+ .. versionadded:: 0.1.0
+ """
+ returnself.by_property("zone",zone)
+
+
[docs]classXADisk(XADiskItem):
+ """A disk in the file system.
+
+ .. versionadded:: 0.1.0
+ """
+ def__init__(self,properties):
+ super().__init__(properties)
+
+ @property
+ defcapacity(self)->'float':
+ """The total number of bytes (free or used) on the disk.
+
+ .. versionadded:: 0.1.0
+ """
+ returnself.xa_elem.capacity()
+
+ @property
+ defejectable(self)->'bool':
+ """Whether the media can be ejected (floppies, CD's, and so on).
+
+ .. versionadded:: 0.1.0
+ """
+ returnself.xa_elem.ejectable()
+
+ @property
+ defformat(self)->'XAEventsApplication.Format':
+ """The file system format of the disk.
+
+ .. versionadded:: 0.1.0
+ """
+ returnXAEventsApplication.Format(self.xa_elem.format())
+
+ @property
+ deffree_space(self)->'float':
+ """The number of free bytes left on the disk.
+
+ .. versionadded:: 0.1.0
+ """
+ returnself.xa_elem.freeSpace()
+
+ @property
+ defignore_privileges(self)->'bool':
+ """Whether to ignore permissions on this disk.
+
+ .. versionadded:: 0.1.0
+ """
+ returnself.xa_elem.ignorePrivileges()
+
+ @property
+ deflocal_volume(self)->'bool':
+ """Whether the media is a local volume (as opposed to a file server).
+
+ .. versionadded:: 0.1.0
+ """
+ returnself.xa_elem.localVolume()
+
+ @property
+ defserver(self)->'str':
+ """The server on which the disk resides, AFP volumes only.
+
+ .. versionadded:: 0.1.0
+ """
+ returnself.xa_elem.server()
+
+ @property
+ defstartup(self)->'bool':
+ """Whether this disk is the boot disk.
+
+ .. versionadded:: 0.1.0
+ """
+ returnself.xa_elem.startup()
+
+ @property
+ defzone(self)->'str':
+ """The zone in which the disk's server resides, AFP volumes only.
+
+ .. versionadded:: 0.1.0
+ """
+ returnself.xa_elem.zone()
+
+
[docs]defaliases(self,filter:Union[dict,None]=None)->'XAAliasList':
+ """Returns a list of aliases, as PyXA objects, matching the given filter.
+
+ .. versionadded:: 0.1.0
+ """
+ self._new_element(self.xa_elem.aliases(),XAAliasList,filter)
+
+
[docs]defdisk_items(self,filter:Union[dict,None]=None)->'XADiskItemList':
+ """Returns a list of disk items, as PyXA objects, matching the given filter.
+
+ .. versionadded:: 0.1.0
+ """
+ self._new_element(self.xa_elem.diskItems(),XADiskItemList,filter)
+
+
[docs]deffiles(self,filter:Union[dict,None]=None)->'XAFileList':
+ """Returns a list of files, as PyXA objects, matching the given filter.
+
+ .. versionadded:: 0.1.0
+ """
+ self._new_element(self.xa_elem.files(),XAFileList,filter)
+
+
[docs]deffile_packages(self,filter:Union[dict,None]=None)->'XAFilePackageList':
+ """Returns a list of file packages, as PyXA objects, matching the given filter.
+
+ .. versionadded:: 0.1.0
+ """
+ self._new_element(self.xa_elem.fileOackages(),XAFilePackageList,filter)
+
+
[docs]deffolders(self,filter:Union[dict,None]=None)->'XAFolderList':
+ """Returns a list of folders, as PyXA objects, matching the given filter.
+
+ .. versionadded:: 0.1.0
+ """
+ self._new_element(self.xa_elem.folders(),XAFolderList,filter)
+
+
+
+
+
[docs]classXADomainList(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.
+
+ .. versionadded:: 0.1.0
+ """
+ def__init__(self,properties:dict,filter:Union[dict,None]=None):
+ super().__init__(properties,XADomain,filter)
+
+
[docs]defid(self)->list['str']:
+ """Retrieves the unique identifier of each domain in the list
+
+ .. versionadded:: 0.1.0
+ """
+ returnlist(self.xa_elem.arrayByApplyingSelector_("id"))
+
+
[docs]defname(self)->list['str']:
+ """Retrieves the name of each domain in the list.
+
+ .. versionadded:: 0.1.0
+ """
+ returnlist(self.xa_elem.arrayByApplyingSelector_("name"))
+
+
[docs]defby_id(self,id:str)->'XADomain':
+ """Retrieves the domain whose ID matches the given ID.
+
+ .. versionadded:: 0.1.0
+ """
+ returnself.by_property("id",id)
+
+
[docs]defby_name(self,name:str)->'XADomain':
+ """Retrieves the domain whose name matches the given name.
+
+ .. versionadded:: 0.1.0
+ """
+ returnself.by_property("name",name)
[docs]deffolders(self,filter:Union[dict,None]=None)->'XAFolderList':
+ """Returns a list of folders, as PyXA objects, matching the given filter.
+
+ .. versionadded:: 0.1.0
+ """
+ self._new_element(self.xa_elem.folders(),XAFolderList,filter)
[docs]deffolders(self,filter:Union[dict,None]=None)->'XAFolderList':
+ """Returns a list of folders, as PyXA objects, matching the given filter.
+
+ .. versionadded:: 0.1.0
+ """
+ self._new_element(self.xa_elem.folders(),XAFolderList,filter)
+
+
+
+
+
[docs]classXAFileList(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.
+
+ .. versionadded:: 0.1.0
+ """
+ def__init__(self,properties:dict,filter:Union[dict,None]=None,object_class=None):
+ ifobject_classisNone:
+ object_class=XAFile
+ super().__init__(properties,filter,object_class)
+
+
[docs]defcreator_type(self)->list['str']:
+ """Retrieves the OSType identifying the application that created each file in the list.
+
+ .. versionadded:: 0.1.0
+ """
+ returnlist(self.xa_elem.arrayByApplyingSelector_("creatorType"))
+
+
[docs]defdefault_application(self)->'XADiskItemList':
+ """Retrieves the applications that will launch if each file in the list is opened.
+
+ .. versionadded:: 0.1.0
+ """
+ ls=self.xa_elem.arrayByApplyingSelector_("defaultApplication")
+ returnself._new_element(ls,XADiskItemList)
+
+
[docs]deffile_type(self)->list['str']:
+ """Retrieves the OSType identifying the type of data contained in each file in the list.
+
+ .. versionadded:: 0.1.0
+ """
+ returnlist(self.xa_elem.arrayByApplyingSelector_("fileType"))
+
+
[docs]defkind(self)->list['str']:
+ """Retrieves the kind of each file in the list.
+
+ .. versionadded:: 0.1.0
+ """
+ returnlist(self.xa_elem.arrayByApplyingSelector_("kind"))
+
+
[docs]defproduct_version(self)->list['str']:
+ """Retrieves the product version of each file in the list.
+
+ .. versionadded:: 0.1.0
+ """
+ returnlist(self.xa_elem.arrayByApplyingSelector_("productVersion"))
+
+
[docs]defshort_version(self)->list['str']:
+ """Retrieves the short version of each file in the list.
+
+ .. versionadded:: 0.1.0
+ """
+ returnlist(self.xa_elem.arrayByApplyingSelector_("shortVersion"))
+
+
[docs]defstationery(self)->list['bool']:
+ """Retrieves the stationery status of each file in the list.
+
+ .. versionadded:: 0.1.0
+ """
+ returnlist(self.xa_elem.arrayByApplyingSelector_("stationery"))
+
+
[docs]deftype_identifier(self)->list['str']:
+ """Retrieves the type identifier of each file in the list.
+
+ .. versionadded:: 0.1.0
+ """
+ returnlist(self.xa_elem.arrayByApplyingSelector_("typeIdentifier"))
+
+
[docs]defversion(self)->list['str']:
+ """Retrieves the version of each file in the list.
+
+ .. versionadded:: 0.1.0
+ """
+ returnlist(self.xa_elem.arrayByApplyingSelector_("version"))
+
+
[docs]defby_creator_type(self,creator_type:str)->'XAFile':
+ """Retrieves the file whose creator type matches the given creator type.
+
+ .. versionadded:: 0.1.0
+ """
+ returnself.by_property("creatorType",creator_type)
+
+
[docs]defby_default_application(self,default_application:'XADiskItem')->'XAFile':
+ """Retrieves the file whose default application matches the given application.
+
+ .. versionadded:: 0.1.0
+ """
+ returnself.by_property("defaultApplication",default_application.xa_elem)
+
+
[docs]defby_file_type(self,file_type:str)->'XAFile':
+ """Retrieves the file whose file type matches the given file type.
+
+ .. versionadded:: 0.1.0
+ """
+ returnself.by_property("fileType",file_type)
+
+
[docs]defby_kind(self,kind:str)->'XAFile':
+ """Retrieves the file whose kind matches the given kind.
+
+ .. versionadded:: 0.1.0
+ """
+ returnself.by_property("kind",kind)
+
+
[docs]defby_product_version(self,product_version:str)->'XAFile':
+ """Retrieves the file whose product version matches the given version.
+
+ .. versionadded:: 0.1.0
+ """
+ returnself.by_property("productVersion",product_version)
+
+
[docs]defby_short_version(self,short_version:str)->'XAFile':
+ """Retrieves the file whose short version matches the given text.
+
+ .. versionadded:: 0.1.0
+ """
+ returnself.by_property("shortVersion",short_version)
+
+
[docs]defby_stationery(self,stationery:bool)->'XAFile':
+ """Retrieves the file whose stationery status matches the given boolean value.
+
+ .. versionadded:: 0.1.0
+ """
+ returnself.by_property("stationery",stationery)
+
+
[docs]defby_type_identifier(self,type_identifier:str)->'XAFile':
+ """Retrieves the file whose type identifier matches the given type identifier.
+
+ .. versionadded:: 0.1.0
+ """
+ returnself.by_property("typeIdentifier",type_identifier)
+
+
[docs]defby_version(self,version:str)->'XAFile':
+ """Retrieves the file whose version matches the given version.
+
+ .. versionadded:: 0.1.0
+ """
+ returnself.by_property("version",version)
+
+
[docs]classXAFile(XADiskItem):
+ """A file in the file system.
+
+ .. versionadded:: 0.1.0
+ """
+ def__init__(self,properties):
+ super().__init__(properties)
+
+ @property
+ defcreator_type(self)->'str':
+ """The OSType identifying the application that created the file.
+
+ .. versionadded:: 0.1.0
+ """
+ returnself.xa_elem.creatorType()
+
+ @property
+ defdefault_application(self)->'XADiskItem':
+ """The application that will launch if the file is opened.
+
+ .. versionadded:: 0.1.0
+ """
+ returnself._new_element(self.xa_elem.defaultApplication(),XADiskItem)
+
+ @default_application.setter
+ defdefault_application(self,default_application:XADiskItem):
+ self.set_property('defaultApplication',default_application.xa_elem)
+
+ @property
+ deffile_type(self)->'str':
+ """The OSType identifying the type of data contained in the file.
+
+ .. versionadded:: 0.1.0
+ """
+ returnself.xa_elem.fileType()
+
+ @property
+ defkind(self)->'str':
+ """The kind of file, as shown in Finder.
+
+ .. versionadded:: 0.1.0
+ """
+ returnself.xa_elem.kind()
+
+ @property
+ defproduct_version(self)->'str':
+ """The version of the product (visible at the top of the "Get Info" window).
+
+ .. versionadded:: 0.1.0
+ """
+ returnself.xa_elem.productVersion()
+
+ @property
+ defshort_version(self)->'str':
+ """The short version of the file.
+
+ .. versionadded:: 0.1.0
+ """
+ returnself.xa_elem.shortVersion()
+
+ @property
+ defstationery(self)->'bool':
+ """Whether the file is a stationery pad.
+
+ .. versionadded:: 0.1.0
+ """
+ returnself.xa_elem.stationery()
+
+ @property
+ deftype_identifier(self)->'str':
+ """The type identifier of the file.
+
+ .. versionadded:: 0.1.0
+ """
+ returnself.xa_elem.typeIdentifier()
+
+ @property
+ defversion(self)->'str':
+ """The version of the file (visible at the bottom of the "Get Info" window).
+
+ .. versionadded:: 0.1.0
+ """
+ returnself.xa_elem.version()
+
+
+
+
+
[docs]classXAFilePackageList(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.
+
+ .. versionadded:: 0.1.0
+ """
+ def__init__(self,properties:dict,filter:Union[dict,None]=None):
+ super().__init__(properties,filter,XAFilePackage)
[docs]defaliases(self,filter:Union[dict,None]=None)->'XAAliasList':
+ """Returns a list of aliases, as PyXA objects, matching the given filter.
+
+ .. versionadded:: 0.1.0
+ """
+ self._new_element(self.xa_elem.aliases(),XAAliasList,filter)
+
+
[docs]defdisk_items(self,filter:Union[dict,None]=None)->'XADiskItemList':
+ """Returns a list of disk items, as PyXA objects, matching the given filter.
+
+ .. versionadded:: 0.1.0
+ """
+ self._new_element(self.xa_elem.diskItems(),XADiskItemList,filter)
+
+
[docs]deffiles(self,filter:Union[dict,None]=None)->'XAFileList':
+ """Returns a list of files, as PyXA objects, matching the given filter.
+
+ .. versionadded:: 0.1.0
+ """
+ self._new_element(self.xa_elem.files(),XAFileList,filter)
+
+
[docs]deffile_packages(self,filter:Union[dict,None]=None)->'XAFilePackageList':
+ """Returns a list of file packages, as PyXA objects, matching the given filter.
+
+ .. versionadded:: 0.1.0
+ """
+ self._new_element(self.xa_elem.filePackages(),XAFilePackageList,filter)
+
+
[docs]deffolders(self,filter:Union[dict,None]=None)->'XAFolderList':
+ """Returns a list of folders, as PyXA objects, matching the given filter.
+
+ .. versionadded:: 0.1.0
+ """
+ self._new_element(self.xa_elem.folders(),XAFolderList,filter)
+
+
+
+
+
[docs]classXAFolderList(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.
+
+ .. versionadded:: 0.1.0
+ """
+ def__init__(self,properties:dict,filter:Union[dict,None]=None):
+ super().__init__(properties,filter,XAFolder)
[docs]defaliases(self,filter:Union[dict,None]=None)->'XAAliasList':
+ """Returns a list of aliases, as PyXA objects, matching the given filter.
+
+ .. versionadded:: 0.1.0
+ """
+ self._new_element(self.xa_elem.aliases(),XAAliasList,filter)
+
+
[docs]defdisk_items(self,filter:Union[dict,None]=None)->'XADiskItemList':
+ """Returns a list of disk items, as PyXA objects, matching the given filter.
+
+ .. versionadded:: 0.1.0
+ """
+ self._new_element(self.xa_elem.diskItems(),XADiskItemList,filter)
+
+
[docs]deffiles(self,filter:Union[dict,None]=None)->'XAFileList':
+ """Returns a list of files, as PyXA objects, matching the given filter.
+
+ .. versionadded:: 0.1.0
+ """
+ self._new_element(self.xa_elem.files(),XAFileList,filter)
+
+
[docs]deffile_packages(self,filter:Union[dict,None]=None)->'XAFilePackageList':
+ """Returns a list of file packages, as PyXA objects, matching the given filter.
+
+ .. versionadded:: 0.1.0
+ """
+ self._new_element(self.xa_elem.filePackages(),XAFilePackageList,filter)
+
+
[docs]deffolders(self,filter:Union[dict,None]=None)->'XAFolderList':
+ """Returns a list of folders, as PyXA objects, matching the given filter.
+
+ :param filter: A dictionary specifying property-value pairs that all returned folders will have, or None
+ :type filter: Union[dict, None]
+ :return: The list of folders
+ :rtype: XAFolderList
+
+ .. versionadded:: 0.1.0
+ """
+ self._new_element(self.xa_elem.folders(),XAFolderList,filter)
+
+
+
+
+
[docs]classXALocalDomainObject(XADomain):
+ """The local domain in the file system.
+
+ .. versionadded:: 0.1.0
+ """
+ def__init__(self,properties):
+ super().__init__(properties)
+
+
+
+
+
[docs]classXANetworkDomainObject(XADomain):
+ """The network domain in the file system.
+
+ .. versionadded:: 0.1.0
+ """
+ def__init__(self,properties):
+ super().__init__(properties)
+
+
+
+
+
[docs]classXASystemDomainObject(XADomain):
+ """The system domain in the file system.
+
+ .. versionadded:: 0.1.0
+ """
+ def__init__(self,properties):
+ super().__init__(properties)
[docs]defhorizontal_stitch(self)->'XAImage':
+ """Horizontally stacks each image in the list.
+
+ The first image in the list is placed at the left side of the resulting image.
+
+ :return: The resulting image after stitching
+ :rtype: XAImage
+
+ .. versionadded:: 0.1.0
+ """
+ returnXAImage.horizontal_stitch(self)
+
+
[docs]defvertical_stitch(self)->'XAImage':
+ """Vertically stacks each image in the list.
+
+ The first image in the list is placed at the bottom side of the resulting image.
+
+ :return: The resulting image after stitching
+ :rtype: XAImage
+
+ .. versionadded:: 0.1.0
+ """
+ returnXAImage.vertical_stitch(self)
+
+
[docs]defadditive_composition(self)->'XAImage':
+ """Creates a composition image by adding the color values of each image in the list.
+
+ :param images: The images to add together
+ :type images: list[XAImage]
+ :return: The resulting image composition
+ :rtype: XAImage
+
+ .. versionadded:: 0.1.0
+ """
+ image_data=[None]*self.xa_elem.count()
+ forindex,imageinenumerate(self.xa_elem):
+ ifisinstance(image,str):
+ image=AppKit.NSImage.alloc().initWithContentsOfURL_(XAPath(image).xa_elem)
+ image_data[index]=Quartz.CIImage.imageWithData_(image.TIFFRepresentation())
+
+ current_composition=None
+ whilelen(image_data)>1:
+ img1=image_data.pop(0)
+ img2=image_data.pop(0)
+ composition_filter=Quartz.CIFilter.filterWithName_("CIAdditionCompositing")
+ composition_filter.setDefaults()
+ composition_filter.setValue_forKey_(img1,"inputImage")
+ composition_filter.setValue_forKey_(img2,"inputBackgroundImage")
+ current_composition=composition_filter.outputImage()
+ image_data.insert(0,current_composition)
+
+ composition_rep=AppKit.NSCIImageRep.imageRepWithCIImage_(current_composition)
+ composition=AppKit.NSImage.alloc().initWithSize_(composition_rep.size())
+ composition.addRepresentation_(composition_rep)
+ returnXAImage(composition)
+
+
[docs]defsubtractive_composition(self)->'XAImage':
+ """Creates a composition image by subtracting the color values of each image in the list successively.
+
+ :param images: The images to create the composition from
+ :type images: list[XAImage]
+ :return: The resulting image composition
+ :rtype: XAImage
+
+ .. versionadded:: 0.1.0
+ """
+ image_data=[None]*self.xa_elem.count()
+ forindex,imageinenumerate(self.xa_elem):
+ ifisinstance(image,str):
+ image=AppKit.NSImage.alloc().initWithContentsOfURL_(XAPath(image).xa_elem)
+ image_data[index]=Quartz.CIImage.imageWithData_(image.TIFFRepresentation())
+
+ current_composition=None
+ whilelen(image_data)>1:
+ img1=image_data.pop(0)
+ img2=image_data.pop(0)
+ composition_filter=Quartz.CIFilter.filterWithName_("CISubtractBlendMode")
+ composition_filter.setDefaults()
+ composition_filter.setValue_forKey_(img1,"inputImage")
+ composition_filter.setValue_forKey_(img2,"inputBackgroundImage")
+ current_composition=composition_filter.outputImage()
+ image_data.insert(0,current_composition)
+
+ composition_rep=AppKit.NSCIImageRep.imageRepWithCIImage_(current_composition)
+ composition=AppKit.NSImage.alloc().initWithSize_(composition_rep.size())
+ composition.addRepresentation_(composition_rep)
+ returnXAImage(composition)
+
+
[docs]defedges(self,intensity:float=1.0)->'XAImageList':
+ """Detects the edges in each image of the list and highlights them colorfully, blackening other areas of the images.
+
+ :param intensity: The degree to which edges are highlighted. Higher is brighter. Defaults to 1.0
+ :type intensity: float
+ :return: The resulting images after applying the filter
+ :rtype: XAImageList
+
+ .. versionadded:: 0.1.0
+ """
+ deffilter_block(image,intensity):
+ filter=Quartz.CIFilter.filterWithName_("CIEdges")
+ filter.setDefaults()
+ filter.setValue_forKey_(intensity,"inputIntensity")
+ returnfilter
+
+ returnself.__apply_filter(filter_block,intensity)
+
+
[docs]defgaussian_blur(self,intensity:float=10)->'XAImageList':
+ """Blurs each image in the list using a Gaussian filter.
+
+ :param intensity: The strength of the blur effect, defaults to 10
+ :type intensity: float
+ :return: The resulting images after applying the filter
+ :rtype: XAImageList
+
+ .. versionadded:: 0.1.0
+ """
+ deffilter_block(image,intensity):
+ filter=Quartz.CIFilter.filterWithName_("CIGaussianBlur")
+ filter.setDefaults()
+ filter.setValue_forKey_(intensity,"inputRadius")
+ returnfilter
+
+ returnself.__apply_filter(filter_block,intensity)
+
+
[docs]defreduce_noise(self,noise_level:float=0.02,sharpness:float=0.4)->'XAImageList':
+ """Reduces noise in each image of the list by sharpening areas with a luminance delta below the specified noise level threshold.
+
+ :param noise_level: The threshold for luminance changes in an area below which will be considered noise, defaults to 0.02
+ :type noise_level: float
+ :param sharpness: The sharpness of the resulting images, defaults to 0.4
+ :type sharpness: float
+ :return: The resulting images after applying the filter
+ :rtype: XAImageList
+
+ .. versionadded:: 0.1.0
+ """
+ deffilter_block(image,noise_level,sharpness):
+ filter=Quartz.CIFilter.filterWithName_("CINoiseReduction")
+ filter.setDefaults()
+ filter.setValue_forKey_(noise_level,"inputNoiseLevel")
+ filter.setValue_forKey_(sharpness,"inputSharpness")
+ returnfilter
+
+ returnself.__apply_filter(filter_block,noise_level,sharpness)
+
+
[docs]defpixellate(self,pixel_size:float=8.0)->'XAImageList':
+ """Pixellates each image in the list.
+
+ :param pixel_size: The size of the pixels, defaults to 8.0
+ :type pixel_size: float
+ :return: The resulting images after applying the filter
+ :rtype: XAImageList
+
+ .. versionadded:: 0.1.0
+ """
+ deffilter_block(image,pixel_size):
+ filter=Quartz.CIFilter.filterWithName_("CIPixellate")
+ filter.setDefaults()
+ filter.setValue_forKey_(pixel_size,"inputScale")
+ returnfilter
+
+ returnself.__apply_filter(filter_block,pixel_size)
+
+
[docs]defoutline(self,threshold:float=0.1)->'XAImageList':
+ """Outlines detected edges within each image of the list in black, leaving the rest transparent.
+
+ :param threshold: The threshold to use when separating edge and non-edge pixels. Larger values produce thinner edge lines. Defaults to 0.1
+ :type threshold: float
+ :return: The resulting images after applying the filter
+ :rtype: XAImageList
+
+ .. versionadded:: 0.1.0
+ """
+ deffilter_block(image,threshold):
+ filter=Quartz.CIFilter.filterWithName_("CILineOverlay")
+ filter.setDefaults()
+ filter.setValue_forKey_(threshold,"inputThreshold")
+ returnfilter
+
+ returnself.__apply_filter(filter_block,threshold)
+
+
[docs]definvert(self)->'XAImageList':
+ """Inverts the colors of each image in the list.
+
+ :return: The resulting images after applying the filter
+ :rtype: XAImageList
+
+ .. versionadded:: 0.1.0
+ """
+ deffilter_block(image):
+ filter=Quartz.CIFilter.filterWithName_("CIColorInvert")
+ filter.setDefaults()
+ returnfilter
+
+ returnself.__apply_filter(filter_block)
+
+
[docs]defsepia(self,intensity:float=1.0)->'XAImageList':
+ """Applies a sepia filter to each image in the list; maps all colors of the images to shades of brown.
+
+ :param intensity: The opacity of the sepia effect. A value of 0 will have no impact on the image. Defaults to 1.0
+ :type intensity: float
+ :return: The resulting images after applying the filter
+ :rtype: XAImageList
+
+ .. versionadded:: 0.1.0
+ """
+ deffilter_block(image,intensity):
+ filter=Quartz.CIFilter.filterWithName_("CISepiaTone")
+ filter.setDefaults()
+ filter.setValue_forKey_(intensity,"inputIntensity")
+ returnfilter
+
+ returnself.__apply_filter(filter_block,intensity)
+
+
[docs]defvignette(self,intensity:float=1.0)->'XAImageList':
+ """Applies vignette shading to the corners of each image in the list.
+
+ :param intensity: The intensity of the vignette effect, defaults to 1.0
+ :type intensity: float
+ :return: The resulting images after applying the filter
+ :rtype: XAImageList
+
+ .. versionadded:: 0.1.0
+ """
+ deffilter_block(image,intensity):
+ filter=Quartz.CIFilter.filterWithName_("CIVignette")
+ filter.setDefaults()
+ filter.setValue_forKey_(intensity,"inputIntensity")
+ returnfilter
+
+ returnself.__apply_filter(filter_block,intensity)
+
+
[docs]defdepth_of_field(self,focal_region:Union[tuple[tuple[int,int],tuple[int,int]],None]=None,intensity:float=10.0,focal_region_saturation:float=1.5)->'XAImageList':
+ """Applies a depth of field filter to each image in the list, simulating a tilt & shift effect.
+
+ :param focal_region: 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
+ :type focal_region: Union[tuple[tuple[int, int], tuple[int, int]], None]
+ :param intensity: 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
+ :type intensity: float
+ :param focal_region_saturation: Adjusts the saturation of the focial region. Higher values increase saturation. Defaults to 1.5 (1.5x default saturation)
+ :type focal_region_saturation: float
+ :return: The resulting images after applying the filter
+ :rtype: XAImageList
+
+ .. versionadded:: 0.1.0
+ """
+ deffilter_block(image,focal_region,intensity,focal_region_saturation):
+ iffocal_regionisNone:
+ center_top=Quartz.CIVector.vectorWithX_Y_(image.size().width/2,image.size().height/3)
+ center_bottom=Quartz.CIVector.vectorWithX_Y_(image.size().width/2,image.size().height/3*2)
+ focal_region=(center_top,center_bottom)
+ else:
+ point1=Quartz.CIVector.vectorWithX_Y_(focal_region[0])
+ point2=Quartz.CIVector.vectorWithX_Y_(focal_region[1])
+ focal_region=(point1,point2)
+
+ filter=Quartz.CIFilter.filterWithName_("CIDepthOfField")
+ filter.setDefaults()
+ filter.setValue_forKey_(focal_region[0],"inputPoint0")
+ filter.setValue_forKey_(focal_region[1],"inputPoint1")
+ filter.setValue_forKey_(intensity,"inputRadius")
+ filter.setValue_forKey_(focal_region_saturation,"inputSaturation")
+ returnfilter
+
+ returnself.__apply_filter(filter_block,focal_region,intensity,focal_region_saturation)
+
+
[docs]defcrystallize(self,crystal_size:float=20.0)->'XAImageList':
+ """Applies a crystallization filter to each image in the list. Creates polygon-shaped color blocks by aggregating pixel values.
+
+ :param crystal_size: The radius of the crystals, defaults to 20.0
+ :type crystal_size: float
+ :return: The resulting images after applying the filter
+ :rtype: XAImageList
+
+ .. versionadded:: 0.1.0
+ """
+ deffilter_block(image,crystal_size):
+ filter=Quartz.CIFilter.filterWithName_("CICrystallize")
+ filter.setDefaults()
+ filter.setValue_forKey_(crystal_size,"inputRadius")
+ returnfilter
+
+ returnself.__apply_filter(filter_block,crystal_size)
+
+
[docs]defcomic(self)->'XAImageList':
+ """Applies a comic filter to each image in the list. Outlines edges and applies a color halftone effect.
+
+ :return: The resulting images after applying the filter
+ :rtype: XAImageList
+
+ .. versionadded:: 0.1.0
+ """
+ deffilter_block(image):
+ filter=Quartz.CIFilter.filterWithName_("CIComicEffect")
+ filter.setDefaults()
+ returnfilter
+
+ returnself.__apply_filter(filter_block)
+
+
[docs]defpointillize(self,point_size:float=20.0)->'XAImageList':
+ """Applies a pointillization filter to each image in the list.
+
+ :param crystal_size: The radius of the points, defaults to 20.0
+ :type crystal_size: float
+ :return: The resulting images after applying the filter
+ :rtype: XAImageList
+
+ .. versionadded:: 0.1.0
+ """
+ deffilter_block(image,point_size):
+ filter=Quartz.CIFilter.filterWithName_("CIPointillize")
+ filter.setDefaults()
+ filter.setValue_forKey_(point_size,"inputRadius")
+ returnfilter
+
+ returnself.__apply_filter(filter_block,point_size)
+
+
[docs]defbloom(self,intensity:float=0.5)->'XAImageList':
+ """Applies a bloom effect to each image in the list. Softens edges and adds a glow.
+
+ :param intensity: The strength of the softening and glow effects, defaults to 0.5
+ :type intensity: float
+ :return: The resulting images after applying the filter
+ :rtype: XAImageList
+
+ .. versionadded:: 0.1.0
+ """
+ deffilter_block(image,intensity):
+ filter=Quartz.CIFilter.filterWithName_("CIBloom")
+ filter.setDefaults()
+ filter.setValue_forKey_(intensity,"inputIntensity")
+ returnfilter
+
+ returnself.__apply_filter(filter_block,intensity)
+
+
[docs]defmonochrome(self,color:XAColor,intensity:float=1.0)->'XAImageList':
+ """Remaps the colors of each image in the list to shades of the specified color.
+
+ :param color: The color of map each images colors to
+ :type color: XAColor
+ :param intensity: The strength of recoloring effect. Higher values map colors to darker shades of the provided color. Defaults to 1.0
+ :type intensity: float
+ :return: The resulting images after applying the filter
+ :rtype: XAImageList
+
+ .. versionadded:: 0.1.0
+ """
+ ci_color=Quartz.CIColor.alloc().initWithColor_(color.xa_elem)
+
+ deffilter_block(image,intensity):
+ filter=Quartz.CIFilter.filterWithName_("CIColorMonochrome")
+ filter.setDefaults()
+ filter.setValue_forKey_(ci_color,"inputColor")
+ filter.setValue_forKey_(intensity,"inputIntensity")
+ returnfilter
+
+ returnself.__apply_filter(filter_block,intensity)
+
+
[docs]defbump(self,center:Union[tuple[int,int],None]=None,radius:float=300.0,curvature:float=0.5)->'XAImageList':
+ """Adds a concave (inward) or convex (outward) bump to each image in the list at the specified location within each image.
+
+ :param center: The center point of the effect, or None to use the center of the image, defaults to None
+ :type center: Union[tuple[int, int], None]
+ :param radius: The radius of the bump in pixels, defaults to 300.0
+ :type radius: float
+ :param curvature: 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
+ :type curvature: float
+ :return: The resulting images after applying the distortion
+ :rtype: XAImageList
+
+ .. versionadded:: 0.1.0
+ """
+ images=self.__partial_init()
+
+ bumped_images=[None]*images.count()
+ defbump_image(image,index,center,radius,curvature):
+ ifcenterisNone:
+ center=Quartz.CIVector.vectorWithX_Y_(image.size().width/2,image.size().height/2)
+ else:
+ center=Quartz.CIVector.vectorWithX_Y_(center[0],center[1])
+
+ img=Quartz.CIImage.imageWithCGImage_(image.CGImage())
+ filter=Quartz.CIFilter.filterWithName_("CIBumpDistortion")
+ filter.setDefaults()
+ filter.setValue_forKey_(img,"inputImage")
+ filter.setValue_forKey_(center,"inputCenter")
+ filter.setValue_forKey_(radius,"inputRadius")
+ filter.setValue_forKey_(curvature,"inputScale")
+ uncropped=filter.valueForKey_(Quartz.kCIOutputImageKey)
+
+ # Crop the result to the original image size
+ cropped=uncropped.imageByCroppingToRect_(Quartz.CGRectMake(0,0,image.size().width*2,image.size().height*2))
+
+ # Convert back to NSImage
+ rep=AppKit.NSCIImageRep.imageRepWithCIImage_(cropped)
+ result=AppKit.NSImage.alloc().initWithSize_(rep.size())
+ result.addRepresentation_(rep)
+ bumped_images[index]=result
+
+ threads=[None]*images.count()
+ forindex,imageinenumerate(images):
+ threads[index]=self._spawn_thread(bump_image,[image,index,center,radius,curvature])
+
+ whileany([t.is_alive()fortinthreads]):
+ time.sleep(0.01)
+
+ self.modified=True
+ self.xa_elem=AppKit.NSMutableArray.alloc().initWithArray_(bumped_images)
+ returnself
+
+
[docs]defpinch(self,center:Union[tuple[int,int],None]=None,intensity:float=0.5)->'XAImageList':
+ """Adds an inward pinch distortion to each image in the list at the specified location within each image.
+
+ :param center: The center point of the effect, or None to use the center of the image, defaults to None
+ :type center: Union[tuple[int, int], None]
+ :param intensity: Controls the scale of the pinch effect. Higher values stretch pixels away from the specified center to a greater degree. Defaults to 0.5
+ :type intensity: float
+ :return: The resulting images after applying the distortion
+ :rtype: XAImageList
+
+ .. versionadded:: 0.1.0
+ """
+ images=self.__partial_init()
+
+ pinched_images=[None]*images.count()
+ defpinch_image(image,index,center,intensity):
+ ifcenterisNone:
+ center=Quartz.CIVector.vectorWithX_Y_(image.size().width/2,image.size().height/2)
+ else:
+ center=Quartz.CIVector.vectorWithX_Y_(center[0],center[1])
+
+ img=Quartz.CIImage.imageWithCGImage_(image.CGImage())
+ filter=Quartz.CIFilter.filterWithName_("CIPinchDistortion")
+ filter.setDefaults()
+ filter.setValue_forKey_(img,"inputImage")
+ filter.setValue_forKey_(center,"inputCenter")
+ filter.setValue_forKey_(intensity,"inputScale")
+ uncropped=filter.valueForKey_(Quartz.kCIOutputImageKey)
+
+ # Crop the result to the original image size
+ cropped=uncropped.imageByCroppingToRect_(Quartz.CGRectMake(0,0,image.size().width*2,image.size().height*2))
+
+ # Convert back to NSImage
+ rep=AppKit.NSCIImageRep.imageRepWithCIImage_(cropped)
+ result=AppKit.NSImage.alloc().initWithSize_(rep.size())
+ result.addRepresentation_(rep)
+ pinched_images[index]=result
+
+ threads=[None]*images.count()
+ forindex,imageinenumerate(images):
+ threads[index]=self._spawn_thread(pinch_image,[image,index,center,intensity])
+
+ whileany([t.is_alive()fortinthreads]):
+ time.sleep(0.01)
+
+ self.modified=True
+ self.xa_elem=AppKit.NSMutableArray.alloc().initWithArray_(pinched_images)
+ returnself
+
+
[docs]deftwirl(self,center:Union[tuple[int,int],None]=None,radius:float=300.0,angle:float=3.14)->'XAImageList':
+ """Adds a twirl distortion to each image in the list by rotating pixels around the specified location within each image.
+
+ :param center: The center point of the effect, or None to use the center of the image, defaults to None
+ :type center: Union[tuple[int, int], None]
+ :param radius: The pixel radius around the centerpoint that defines the area to apply the effect to, defaults to 300.0
+ :type radius: float
+ :param angle: The angle of the twirl in radians, defaults to 3.14
+ :type angle: float
+ :return: The resulting images after applying the distortion
+ :rtype: XAImageList
+
+ .. versionadded:: 0.1.0
+ """
+ images=self.__partial_init()
+
+ twirled_images=[None]*images.count()
+ deftwirl_image(image,index,center,radius,angle):
+ ifcenterisNone:
+ center=Quartz.CIVector.vectorWithX_Y_(image.size().width/2,image.size().height/2)
+ else:
+ center=Quartz.CIVector.vectorWithX_Y_(center[0],center[1])
+
+ img=Quartz.CIImage.imageWithCGImage_(image.CGImage())
+ filter=Quartz.CIFilter.filterWithName_("CITwirlDistortion")
+ filter.setDefaults()
+ filter.setValue_forKey_(img,"inputImage")
+ filter.setValue_forKey_(center,"inputCenter")
+ filter.setValue_forKey_(radius,"inputRadius")
+ filter.setValue_forKey_(angle,"inputAngle")
+ uncropped=filter.valueForKey_(Quartz.kCIOutputImageKey)
+
+ # Crop the result to the original image size
+ cropped=uncropped.imageByCroppingToRect_(Quartz.CGRectMake(0,0,image.size().width*2,image.size().height*2))
+
+ # Convert back to NSImage
+ rep=AppKit.NSCIImageRep.imageRepWithCIImage_(cropped)
+ result=AppKit.NSImage.alloc().initWithSize_(rep.size())
+ result.addRepresentation_(rep)
+ twirled_images[index]=result
+
+ threads=[None]*images.count()
+ forindex,imageinenumerate(images):
+ threads[index]=self._spawn_thread(twirl_image,[image,index,center,radius,angle])
+
+ whileany([t.is_alive()fortinthreads]):
+ time.sleep(0.01)
+
+ self.modified=True
+ self.xa_elem=AppKit.NSMutableArray.alloc().initWithArray_(twirled_images)
+ returnself
+
+
[docs]defauto_enhance(self,correct_red_eye:bool=False,crop_to_features:bool=False,correct_rotation:bool=False)->'XAImageList':
+ """Attempts to enhance each image in the list by applying suggested filters.
+
+ :param correct_red_eye: Whether to attempt red eye removal, defaults to False
+ :type correct_red_eye: bool, optional
+ :param crop_to_features: Whether to crop the images to focus on their main features, defaults to False
+ :type crop_to_features: bool, optional
+ :param correct_rotation: Whether attempt perspective correction by rotating the images, defaults to False
+ :type correct_rotation: bool, optional
+ :return: The list of enhanced images
+ :rtype: XAImageList
+
+ .. versionadded:: 0.1.0
+ """
+ images=self.__partial_init()
+
+ enhanced_images=[None]*images.count()
+ defenhance_image(image,index):
+ ci_image=Quartz.CIImage.imageWithCGImage_(image.CGImage())
+
+ options={
+ Quartz.kCIImageAutoAdjustRedEye:correct_red_eye,
+ Quartz.kCIImageAutoAdjustCrop:crop_to_features,
+ Quartz.kCIImageAutoAdjustLevel:correct_rotation
+ }
+
+ enhancements=ci_image.autoAdjustmentFiltersWithOptions_(options)
+ forfilterinenhancements:
+ filter.setValue_forKey_(ci_image,"inputImage")
+ ci_image=filter.outputImage()
+
+ # Crop the result to the original image size
+ cropped=ci_image.imageByCroppingToRect_(Quartz.CGRectMake(0,0,image.size().width*2,image.size().height*2))
+
+ # Convert back to NSImage
+ rep=AppKit.NSCIImageRep.imageRepWithCIImage_(cropped)
+ result=AppKit.NSImage.alloc().initWithSize_(rep.size())
+ result.addRepresentation_(rep)
+ enhanced_images[index]=result
+
+ threads=[None]*images.count()
+ forindex,imageinenumerate(images):
+ threads[index]=self._spawn_thread(enhance_image,[image,index])
+
+ whileany([t.is_alive()fortinthreads]):
+ time.sleep(0.01)
+
+ self.modified=True
+ self.xa_elem=AppKit.NSMutableArray.alloc().initWithArray_(enhanced_images)
+ returnself
[docs]defrotate(self,degrees:float)->'XAImageList':
+ """Rotates each image in the list by the specified amount of degrees.
+
+ :param degrees: The number of degrees to rotate the images by
+ :type degrees: float
+ :return: The list of rotated images
+ :rtype: XAImageList
+
+ .. versionadded:: 0.1.0
+ """
+ sinDegrees=abs(math.sin(degrees*math.pi/180.0))
+ cosDegrees=abs(math.cos(degrees*math.pi/180.0))
+
+ images=self.__partial_init()
+
+ rotated_images=[None]*images.count()
+ defrotate_image(image,index):
+ new_size=Quartz.CGSizeMake(image.size().height*sinDegrees+image.size().width*cosDegrees,image.size().width*sinDegrees+image.size().height*cosDegrees)
+ rotated_image=AppKit.NSImage.alloc().initWithSize_(new_size)
+
+ imageBounds=Quartz.CGRectMake((new_size.width-image.size().width)/2,(new_size.height-image.size().height)/2,image.size().width,image.size().height)
+
+ transform=AppKit.NSAffineTransform.alloc().init()
+ transform.translateXBy_yBy_(new_size.width/2,new_size.height/2)
+ transform.rotateByDegrees_(degrees)
+ transform.translateXBy_yBy_(-new_size.width/2,-new_size.height/2)
+
+ rotated_image.lockFocus()
+ transform.concat()
+ image.drawInRect_fromRect_operation_fraction_(imageBounds,Quartz.CGRectZero,AppKit.NSCompositingOperationCopy,1.0)
+ rotated_image.unlockFocus()
+
+ rotated_images[index]=rotated_image
+
+ threads=[None]*images.count()
+ forindex,imageinenumerate(images):
+ threads[index]=self._spawn_thread(rotate_image,[image,index])
+
+ whileany([t.is_alive()fortinthreads]):
+ time.sleep(0.01)
+
+ self.modified=True
+ self.xa_elem=AppKit.NSMutableArray.alloc().initWithArray_(rotated_images)
+ returnself
+
+
[docs]defcrop(self,size:tuple[int,int],corner:Union[tuple[int,int],None]=None)->'XAImageList':
+ """Crops each image in the list to the specified dimensions.
+
+ :param size: The dimensions to crop each image to
+ :type size: tuple[int, int]
+ :param corner: The bottom-left location to crom each image from, or None to use (0, 0), defaults to None
+ :type corner: Union[tuple[int, int], None]
+ :return: The list of cropped images
+ :rtype: XAImageList
+
+ .. versionadded:: 0.1.0
+ """
+ ifcornerisNone:
+ # No corner provided -- use (0,0) by default
+ corner=(0,0)
+
+ images=self.__partial_init()
+
+ cropped_images=[None]*images.count()
+ defcrop_image(image,index):
+ cropped_image=AppKit.NSImage.alloc().initWithSize_(AppKit.NSMakeSize(size[0],size[1]))
+ imageBounds=AppKit.NSMakeRect(corner[0],corner[1],image.size().width,image.size().height)
+
+ cropped_image.lockFocus()
+ image.drawInRect_(imageBounds)
+ cropped_image.unlockFocus()
+ cropped_images[index]=cropped_image
+
+ threads=[None]*images.count()
+ forindex,imageinenumerate(images):
+ threads[index]=self._spawn_thread(crop_image,[image,index])
+
+ whileany([t.is_alive()fortinthreads]):
+ time.sleep(0.01)
+
+ self.modified=True
+ self.xa_elem=AppKit.NSMutableArray.alloc().initWithArray_(cropped_images)
+ returnself
+
+
[docs]defscale(self,scale_factor_x:float,scale_factor_y:Union[float,None]=None)->'XAImageList':
+ """Scales each image in the list by the specified horizontal and vertical factors.
+
+ :param scale_factor_x: The factor by which to scale each image in the X dimension
+ :type scale_factor_x: float
+ :param scale_factor_y: The factor by which to scale each image in the Y dimension, or None to match the horizontal factor, defaults to None
+ :type scale_factor_y: Union[float, None]
+ :return: The list of scaled images
+ :rtype: XAImageList
+
+ .. versionadded:: 0.1.0
+ """
+ ifscale_factor_yisNone:
+ scale_factor_y=scale_factor_x
+
+ images=self.__partial_init()
+
+ scaled_images=[None]*self.xa_elem.count()
+ defscale_image(image,index):
+ scaled_image=AppKit.NSImage.alloc().initWithSize_(AppKit.NSMakeSize(image.size().width*scale_factor_x,image.size().height*scale_factor_y))
+ imageBounds=AppKit.NSMakeRect(0,0,image.size().width,image.size().height)
+
+ transform=AppKit.NSAffineTransform.alloc().init()
+ transform.scaleXBy_yBy_(scale_factor_x,scale_factor_y)
+
+ scaled_image.lockFocus()
+ transform.concat()
+ image.drawInRect_fromRect_operation_fraction_(imageBounds,Quartz.CGRectZero,AppKit.NSCompositingOperationCopy,1.0)
+ scaled_image.unlockFocus()
+ scaled_images[index]=scaled_image
+
+ threads=[None]*self.xa_elem.count()
+ forindex,imageinenumerate(images):
+ threads[index]=self._spawn_thread(scale_image,[image,index])
+
+ whileany([t.is_alive()fortinthreads]):
+ time.sleep(0.01)
+
+ self.modified=True
+ self.xa_elem=AppKit.NSMutableArray.alloc().initWithArray_(scaled_images)
+ returnself
+
+
[docs]defpad(self,horizontal_border_width:int=50,vertical_border_width:int=50,pad_color:Union[XAColor,None]=None)->'XAImageList':
+ """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.
+
+ :param horizontal_border_width: The border width, in pixels, in the x-dimension, defaults to 50
+ :type horizontal_border_width: int
+ :param vertical_border_width: The border width, in pixels, in the y-dimension, defaults to 50
+ :type vertical_border_width: int
+ :param pad_color: The color of the border, or None for a white border, defaults to None
+ :type pad_color: Union[XAColor, None]
+ :return: The list of padded images
+ :rtype: XAImageList
+
+ .. versionadded:: 0.1.0
+ """
+ ifpad_colorisNone:
+ # No color provided -- use white by default
+ pad_color=XAColor.white()
+
+ images=self.__partial_init()
+
+ padded_images=[None]*images.count()
+ defpad_image(image,index):
+ new_width=image.size().width+horizontal_border_width*2
+ new_height=image.size().height+vertical_border_width*2
+ color_swatch=pad_color.make_swatch(new_width,new_height)
+
+ color_swatch.xa_elem.lockFocus()
+ bounds=AppKit.NSMakeRect(horizontal_border_width,vertical_border_width,image.size().width,image.size().height)
+ image.drawInRect_(bounds)
+ color_swatch.xa_elem.unlockFocus()
+ padded_images[index]=color_swatch.xa_elem
+
+ threads=[None]*images.count()
+ forindex,imageinenumerate(images):
+ threads[index]=self._spawn_thread(pad_image,[image,index])
+
+ whileany([t.is_alive()fortinthreads]):
+ time.sleep(0.01)
+
+ self.modified=True
+ self.xa_elem=AppKit.NSMutableArray.alloc().initWithArray_(padded_images)
+ returnself
+
+
[docs]defoverlay_image(self,image:'XAImage',location:Union[tuple[int,int],None]=None,size:Union[tuple[int,int],None]=None)->'XAImageList':
+ """Overlays an image on top of each image in the list, at the specified location, with the specified size.
+
+ :param image: The image to overlay on top of each image in the list
+ :type image: XAImage
+ :param location: 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
+ :type location: Union[tuple[int, int], None]
+ :param size: 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
+ :type size: Union[tuple[int, int], None]
+ :return: The list of images with the specified image overlaid on top of them
+ :rtype: XAImageList
+
+ .. versionadded:: 0.1.0
+ """
+ iflocationisNone:
+ # No location provided -- use the bottom-left point of the background image by default
+ location=(0,0)
+
+ images=self.__partial_init()
+ overlayed_images=[None]*images.count()
+ defoverlay_image(img,index,image,size,location):
+ ifsizeisNone:
+ # No dimensions provided -- use size of overlay image by default
+ size=image.size
+ elifsize==(-1,-1):
+ # Use remaining width/height of background image
+ size=(img.size().width-location[0],img.size().height-location[1])
+ elifsize[0]==-1:
+ # Use remaining width of background image + provided height
+ size=(img.size().width-location[0],size[1])
+ elifsize[1]==-1:
+ # Use remaining height of background image + provided width
+ size=(size[1],img.size().width-location[1])
+
+ img.lockFocus()
+ bounds=AppKit.NSMakeRect(location[0],location[1],size[0],size[1])
+ image.xa_elem.drawInRect_(bounds)
+ img.unlockFocus()
+ overlayed_images[index]=img
+
+ threads=[None]*images.count()
+ forindex,imginenumerate(images):
+ threads[index]=self._spawn_thread(overlay_image,[img,index,image,size,location])
+
+ whileany([t.is_alive()fortinthreads]):
+ time.sleep(0.01)
+
+ self.modified=True
+ self.xa_elem=AppKit.NSMutableArray.alloc().initWithArray_(overlayed_images)
+ returnself
+
+
[docs]defoverlay_text(self,text:str,location:Union[tuple[int,int],None]=None,font_size:float=12,font_color:Union[XAColor,None]=None)->'XAImageList':
+ """Overlays text of the specified size and color at the provided location within each image of the list.
+
+ :param text: The text to overlay onto each image of the list
+ :type text: str
+ :param location: The bottom-left point of the start of the text, or None to use (5, 5), defaults to None
+ :type location: Union[tuple[int, int], None]
+ :param font_size: The font size, in pixels, of the text, defaults to 12
+ :type font_size: float
+ :param font_color: The color of the text, or None to use black, defaults to None
+ :type font_color: XAColor
+ :return: The list of images with the specified text overlaid on top of them
+ :rtype: XAImageList
+
+ .. versionadded:: 0.1.0
+ """
+ iflocationisNone:
+ # No location provided -- use (5, 5) by default
+ location=(5,5)
+
+ iffont_colorisNone:
+ # No color provided -- use black by default
+ font_color=XAColor.black()
+
+ font=AppKit.NSFont.userFontOfSize_(font_size)
+ images=self.__partial_init()
+ overlayed_images=[None]*self.xa_elem.count()
+ defoverlay_text(image,index):
+ textRect=Quartz.CGRectMake(location[0],0,image.size().width-location[0],location[1])
+ attributes={
+ AppKit.NSFontAttributeName:font,
+ AppKit.NSForegroundColorAttributeName:font_color.xa_elem
+ }
+
+ image.lockFocus()
+ AppKit.NSString.alloc().initWithString_(text).drawInRect_withAttributes_(textRect,attributes)
+ image.unlockFocus()
+ overlayed_images[index]=image
+
+ threads=[None]*self.xa_elem.count()
+ forindex,imageinenumerate(images):
+ threads[index]=self._spawn_thread(overlay_text,[image,index])
+
+ whileany([t.is_alive()fortinthreads]):
+ time.sleep(0.01)
+
+ self.modified=True
+ self.xa_elem=AppKit.NSMutableArray.alloc().initWithArray_(overlayed_images)
+ returnself
+
+
[docs]defextract_text(self)->list[str]:
+ """Extracts and returns a list of all visible text in each image of the list.
+
+ :return: The array of extracted text strings
+ :rtype: 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', ...]
+
+ .. versionadded:: 0.1.0
+ """
+ images=self.__partial_init()
+
+ extracted_strings=[None]*self.xa_elem.count()
+ defget_text(image,index):
+ # Prepare CGImage
+ ci_image=Quartz.CIImage.imageWithCGImage_(image.CGImage())
+ context=Quartz.CIContext.alloc().initWithOptions_(None)
+ img=context.createCGImage_fromRect_(ci_image,ci_image.extent())
+
+ # Handle request completion
+ image_strings=[]
+ defrecognize_text_handler(request,error):
+ observations=request.results()
+ forobservationinobservations:
+ recognized_strings=observation.topCandidates_(1)[0].string()
+ image_strings.append(recognized_strings)
+
+ # Perform request and return extracted text
+ request=Vision.VNRecognizeTextRequest.alloc().initWithCompletionHandler_(recognize_text_handler)
+ request_handler=Vision.VNImageRequestHandler.alloc().initWithCGImage_options_(img,None)
+ request_handler.performRequests_error_([request],None)
+ extracted_strings[index]=image_strings
+
+ threads=[None]*self.xa_elem.count()
+ forindex,imageinenumerate(images):
+ threads[index]=self._spawn_thread(get_text,[image,index])
+
+ whileany([t.is_alive()fortinthreads]):
+ time.sleep(0.01)
+
+ returnextracted_strings
+
+
[docs]defshow_in_preview(self):
+ """Opens each image in the list in Preview.
+
+ .. versionadded:: 0.1.0
+ """
+ forimageinself:
+ image.show_in_preview()
+
+
[docs]defsave(self,file_paths:list[Union[XAPath,str]]):
+ """Saves each image to a file on the disk.
+
+ :param file_path: The path at which to save the image file. Any existing file at that location will be overwritten, defaults to None
+ :type file_path: Union[XAPath, str, None]
+
+ .. versionadded:: 0.1.0
+ """
+ forindex,imageinenumerate(self):
+ path=None
+ iflen(file_paths)>index:
+ path=file_paths[index]
+ image.save(path)
+
+
[docs]defget_clipboard_representation(self)->list[AppKit.NSImage]:
+ """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
+
+ :return: A list of media item file URLs
+ :rtype: list[NSURL]
+
+ .. versionadded:: 0.0.8
+ """
+ data=[]
+ forimageinself.__partial_init():
+ ifimage.TIFFRepresentation():
+ data.append(image)
+ returndata
+
+
[docs]classXAImage(XAObject,XAClipboardCodable):
+ """A wrapper around NSImage with specialized automation methods.
+
+ .. versionadded:: 0.0.2
+ """
+
+ def__init__(self,image_reference:Union[str,XAPath,AppKit.NSURL,AppKit.NSImage,None]=None,data:Union[AppKit.NSData,None]=None):
+ self.size:tuple[int,int]#: The dimensions of the image
+ self.file:Union[XAPath,None]=None#: The path to the image file, if one exists
+ self.data:str#: The TIFF representation of the image
+ self.modified:bool=False#: Whether the image data has been modified since the object was originally created
+
+ self.xa_elem=None
+
+ self.__vibrance=None
+ self.__gamma=None
+ self.__tint=None
+ self.__temperature=None
+ self.__white_point=None
+ self.__highlight=None
+ self.__shadow=None
+
+ ifdataisnotNone:
+ # Deprecated as of 0.1.0 -- Pass data as the image_reference instead
+ self.xa_elem=AppKit.NSImage.alloc().initWithData_(data)
+ else:
+ ifimage_referenceisNone:
+ # No reference provided, just initialize a blank image
+ self.xa_elem=AppKit.NSImage.alloc().init()
+ else:
+ self.file=image_reference
+ ifisinstance(image_reference,dict):
+ # Image reference is provided by an XAList
+ self.xa_elem=image_reference["element"]
+ ifisinstance(self.xa_elem,str):
+ # The reference is a string -- reinitialize using it
+ self.file=self.xa_elem
+ self.xa_elem=XAImage(self.xa_elem).xa_elem
+ elifisinstance(self.xa_elem,XAImage):
+ # The reference is another XAImage object
+ self.file=self.xa_elem.file
+ self.xa_elem=self.xa_elem.xa_elem
+
+ elifisinstance(image_reference,AppKit.NSImage):
+ # The reference is an Objective-C image object
+ self.xa_elem=AppKit.NSImage.alloc().initWithData_(image_reference.TIFFRepresentation())
+
+ elifisinstance(image_reference,AppKit.NSData):
+ # The reference is raw image data
+ self.xa_elem=AppKit.NSImage.alloc().initWithData_(data)
+
+ elifisinstance(image_reference,XAPath):
+ # The reference is an XAPath
+ self.file=image_reference.path
+ self.xa_elem=AppKit.NSImage.alloc().initWithContentsOfURL_(image_reference.xa_elem)
+
+ elifisinstance(image_reference,XAURL):
+ # The reference is an XAURL
+ self.file=image_reference.url
+ self.xa_elem=AppKit.NSImage.alloc().initWithContentsOfURL_(image_reference.xa_elem)
+
+ elifisinstance(image_reference,XAImage):
+ # The reference is another XAImage
+ self.file=image_reference.file
+ self.xa_elem=image_reference.xa_elem
+
+ elifisinstance(image_reference,str):
+ # The reference is to a file or a none-file URL
+ if"://"inimage_reference:
+ # The reference is to a non-file URL
+ image_reference=XAURL(image_reference).xa_elem
+ self.xa_elem=AppKit.NSImage.alloc().initWithContentsOfURL_(image_reference)
+ elifos.path.exists(image_reference)oros.path.exists(os.getcwd()+"/"+image_reference):
+ # The reference is to a file
+ image_reference=XAPath(image_reference).xa_elem
+ self.xa_elem=AppKit.NSImage.alloc().initWithContentsOfURL_(image_reference)
+ else:
+ # The reference is just text -- make an image out of it!
+ font=AppKit.NSFont.monospacedSystemFontOfSize_weight_(15,AppKit.NSFontWeightMedium)
+ text=AppKit.NSString.alloc().initWithString_(image_reference)
+ attributes={
+ AppKit.NSFontAttributeName:font,
+ AppKit.NSForegroundColorAttributeName:XAColor.black().xa_elem
+ }
+ text_size=text.sizeWithAttributes_(attributes)
+
+ # Make a white background to overlay the text on
+ swatch=XAColor.white().make_swatch(text_size.width+20,text_size.height+20)
+ text_rect=AppKit.NSMakeRect(10,10,text_size.width,text_size.height)
+
+ # Overlay the text
+ swatch.xa_elem.lockFocus()
+ text.drawInRect_withAttributes_(text_rect,attributes)
+ swatch.xa_elem.unlockFocus()
+ self.xa_elem=swatch.xa_elem
+
+ elifisinstance(image_reference,XAObject):
+ # Must obtain the image representation using the XAImageLike protocol
+ self.xa_elem=XAImage(image_reference.get_image_representation()).xa_elem
+
+ def__update_image(self,modified_image:Quartz.CIImage)->'XAImage':
+ # Crop the result to the original image size
+ cropped=modified_image.imageByCroppingToRect_(Quartz.CGRectMake(0,0,self.size[0]*2,self.size[1]*2))
+
+ # Convert back to NSImage
+ rep=AppKit.NSCIImageRep.imageRepWithCIImage_(cropped)
+ result=AppKit.NSImage.alloc().initWithSize_(rep.size())
+ result.addRepresentation_(rep)
+
+ # Update internal data
+ self.xa_elem=result
+ self.modified=True
+ returnself
+
+ @property
+ defsize(self)->tuple[int,int]:
+ """The dimensions of the image, in pixels.
+
+ .. versionadded:: 0.1.0
+ """
+ returntuple(self.xa_elem.size())
+
+ @property
+ defdata(self)->AppKit.NSData:
+ returnself.xa_elem.TIFFRepresentation()
+
+ @property
+ defhas_alpha_channel(self)->bool:
+ """Whether the image has an alpha channel or not.
+
+ .. versionadded:: 0.1.0
+ """
+ reps=self.xa_elem.representations()
+ iflen(reps)>0:
+ returnreps[0].hasAlpha()
+ # TODO: Make sure this is never a false negative
+ returnFalse
+
+ @property
+ defis_opaque(self)->bool:
+ """Whether the image contains transparent pixels or not.
+
+ .. versionadded:: 0.1.0
+ """
+ reps=self.xa_elem.representations()
+ iflen(reps)>0:
+ returnreps[0].isOpaque()
+ # TODO: Make sure this is never a false negative
+ returnFalse
+
+ @property
+ defcolor_space_name(self)->Union[str,None]:
+ """The name of the color space that the image currently uses.
+
+ .. versionadded:: 0.1.0
+ """
+ reps=self.xa_elem.representations()
+ iflen(reps)>0:
+ returnreps[0].colorSpaceName()
+ # TODO: Make sure this is never a false negative
+ returnNone
+
+ @property
+ defgamma(self)->float:
+ """The gamma value for the image, once it has been manually set. Otherwise, the value is None.
+
+ .. versionadded:: 0.1.0
+ """
+ ifself.__gammaisnotNone:
+ returnself.__gamma
+ return-1
+
+ @gamma.setter
+ defgamma(self,gamma:float):
+ self.__gamma=gamma
+ image=Quartz.CIImage.imageWithData_(self.data)
+ filter=Quartz.CIFilter.filterWithName_("CIGammaAdjust")
+ filter.setDefaults()
+ filter.setValue_forKey_(image,"inputImage")
+ filter.setValue_forKey_(gamma,"inputPower")
+ uncropped=filter.valueForKey_(Quartz.kCIOutputImageKey)
+ self.__update_image(uncropped)
+
+ @property
+ defvibrance(self)->Union[float,None]:
+ """The vibrance value for the image, once it has been manually set. Otherwise, the value is None.
+
+ .. versionadded:: 0.1.0
+ """
+ ifself.__vibranceisnotNone:
+ returnself.__vibrance
+ return-1
+
+ @vibrance.setter
+ defvibrance(self,vibrance:float=1):
+ self.__vibrance=vibrance
+ image=Quartz.CIImage.imageWithData_(self.data)
+ filter=Quartz.CIFilter.filterWithName_("CIVibrance")
+ filter.setDefaults()
+ filter.setValue_forKey_(image,"inputImage")
+ filter.setValue_forKey_(vibrance,"inputAmount")
+ uncropped=filter.valueForKey_(Quartz.kCIOutputImageKey)
+ returnself.__update_image(uncropped)
+
+ @property
+ deftint(self)->Union[float,None]:
+ """The tint setting for the image, once it has been manually set. Otherwise, the value is None.
+
+ .. versionadded:: 0.1.0
+ """
+ ifself.__tintisnotNone:
+ returnself.__tint
+ return-1
+
+ @tint.setter
+ deftint(self,tint:float):
+ # -100 to 100
+ temp_and_tint=Quartz.CIVector.vectorWithX_Y_(6500,tint)
+ self.__tint=tint
+ image=Quartz.CIImage.imageWithData_(self.data)
+ filter=Quartz.CIFilter.filterWithName_("CITemperatureAndTint")
+ filter.setDefaults()
+ filter.setValue_forKey_(image,"inputImage")
+ filter.setValue_forKey_(temp_and_tint,"inputTargetNeutral")
+ uncropped=filter.valueForKey_(Quartz.kCIOutputImageKey)
+ self.__update_image(uncropped)
+
+ @property
+ deftemperature(self)->Union[float,None]:
+ """The temperature setting for the image, once it has been manually set. Otherwise, the value is None.
+
+ .. versionadded:: 0.1.0
+ """
+ ifself.__temperatureisnotNone:
+ returnself.__temperature
+ return-1
+
+ @temperature.setter
+ deftemperature(self,temperature:float):
+ # 2000 to inf
+ temp_and_tint=Quartz.CIVector.vectorWithX_Y_(temperature,0)
+ self.__temperature=temperature
+ image=Quartz.CIImage.imageWithData_(self.data)
+ filter=Quartz.CIFilter.filterWithName_("CITemperatureAndTint")
+ filter.setDefaults()
+ filter.setValue_forKey_(image,"inputImage")
+ filter.setValue_forKey_(temp_and_tint,"inputTargetNeutral")
+ uncropped=filter.valueForKey_(Quartz.kCIOutputImageKey)
+ self.__update_image(uncropped)
+
+ @property
+ defwhite_point(self)->Union['XAColor',None]:
+ """The white point setting for the image, once it has been manually set. Otherwise, the value is None.
+
+ .. versionadded:: 0.1.0
+ """
+ ifself.__white_pointisnotNone:
+ returnself.__white_point
+ return-1
+
+ @white_point.setter
+ defwhite_point(self,white_point:XAColor):
+ self.__white_point=white_point
+ ci_white_point=Quartz.CIColor.alloc().initWithColor_(white_point.xa_elem)
+ image=Quartz.CIImage.imageWithData_(self.data)
+ filter=Quartz.CIFilter.filterWithName_("CIWhitePointAdjust")
+ filter.setDefaults()
+ filter.setValue_forKey_(image,"inputImage")
+ filter.setValue_forKey_(ci_white_point,"inputColor")
+ uncropped=filter.valueForKey_(Quartz.kCIOutputImageKey)
+ self.__update_image(uncropped)
+
+ @property
+ defhighlight(self)->float:
+ """The highlight setting for the image, once it has been manually set. Otherwise, the value is None.
+
+ .. versionadded:: 0.1.0
+ """
+ ifself.__highlightisnotNone:
+ returnself.__highlight
+ return-1
+
+ @highlight.setter
+ defhighlight(self,highlight:float):
+ self.__highlight=highlight
+ image=Quartz.CIImage.imageWithData_(self.data)
+ filter=Quartz.CIFilter.filterWithName_("CIHighlightShadowAdjust")
+ filter.setDefaults()
+ filter.setValue_forKey_(image,"inputImage")
+ filter.setValue_forKey_(highlight,"inputHighlightAmount")
+ uncropped=filter.valueForKey_(Quartz.kCIOutputImageKey)
+ self.__update_image(uncropped)
+
+ @property
+ defshadow(self)->float:
+ """The shadow setting for the image, once it has been manually set. Otherwise, the value is None.
+
+ .. versionadded:: 0.1.0
+ """
+ ifself.__shadowisnotNone:
+ returnself.__shadow
+ return-1
+
+ @shadow.setter
+ defshadow(self,shadow:float):
+ self.__shadow=shadow
+ image=Quartz.CIImage.imageWithData_(self.data)
+ filter=Quartz.CIFilter.filterWithName_("CIHighlightShadowAdjust")
+ filter.setDefaults()
+ filter.setValue_forKey_(image,"inputImage")
+ filter.setValue_forKey_(self.__highlightor1,"inputHighlightAmount")
+ filter.setValue_forKey_(shadow,"inputShadowAmount")
+ uncropped=filter.valueForKey_(Quartz.kCIOutputImageKey)
+ self.__update_image(uncropped)
+
+
[docs]defopen(*images:Union[str,XAPath,list[Union[str,XAPath]]])->Union['XAImage',XAImageList]:
+ """Initializes one or more images from files.
+
+ :param images: The image(s) to open
+ :type images: Union[str, XAPath, list[Union[str, XAPath]]]
+ :return: The newly created image object, or a list of image objects
+ :rtype: Union[XAImage, XAImageList]
+
+ .. versionadded:: 0.1.0
+ """
+ iflen(images)==1:
+ images=images[0]
+
+ ifisinstance(images,list)orisinstance(images,tuple):
+ returnXAImageList({"element":images})
+ else:
+ returnXAImage(images)
+
+
[docs]defimage_from_text(text:str,font_size:int=15,font_color:XAColor=XAColor.black(),background_color:XAColor=XAColor.white(),inset:int=10)->'XAImage':
+ """Initializes an image of the provided text overlaid on the specified background color.
+
+ :param text: The text to create an image of
+ :type text: str
+ :param font_size: The font size of the text, defaults to 15
+ :type font_size: int, optional
+ :param font_color: The color of the text, defaults to XAColor.black()
+ :type font_color: XAColor, optional
+ :param background_color: The color to overlay the text on top of, defaults to XAColor.white()
+ :type background_color: XAColor, optional
+ :param inset: The width of the space between the text and the edge of the background color in the resulting image, defaults to 10
+ :type inset: int, optional
+ :return: XAImage
+ :rtype: The resulting image object
+
+ .. versionadded:: 0.1.0
+ """
+ font=AppKit.NSFont.monospacedSystemFontOfSize_weight_(font_size,AppKit.NSFontWeightMedium)
+ text=AppKit.NSString.alloc().initWithString_(text)
+ attributes={
+ AppKit.NSFontAttributeName:font,
+ AppKit.NSForegroundColorAttributeName:font_color.xa_elem
+ }
+ text_size=text.sizeWithAttributes_(attributes)
+
+ # Make a white background to overlay the text on
+ swatch=background_color.make_swatch(text_size.width+inset*2,text_size.height+inset*2)
+ text_rect=AppKit.NSMakeRect(inset,inset,text_size.width,text_size.height)
+
+ # Overlay the text
+ swatch.xa_elem.lockFocus()
+ text.drawInRect_withAttributes_(text_rect,attributes)
+ swatch.xa_elem.unlockFocus()
+ returnswatch
+
+
[docs]defedges(self,intensity:float=1.0)->'XAImage':
+ """Detects the edges in the image and highlights them colorfully, blackening other areas of the image.
+
+ :param intensity: The degree to which edges are highlighted. Higher is brighter. Defaults to 1.0
+ :type intensity: float
+ :return: The resulting image after applying the filter
+ :rtype: XAImage
+
+ .. versionadded:: 0.1.0
+ """
+ image=Quartz.CIImage.imageWithData_(self.data)
+ filter=Quartz.CIFilter.filterWithName_("CIEdges")
+ filter.setDefaults()
+ filter.setValue_forKey_(image,"inputImage")
+ filter.setValue_forKey_(intensity,"inputIntensity")
+ uncropped=filter.valueForKey_(Quartz.kCIOutputImageKey)
+ returnself.__update_image(uncropped)
+
+
[docs]defgaussian_blur(self,intensity:float=10)->'XAImage':
+ """Blurs the image using a Gaussian filter.
+
+ :param intensity: The strength of the blur effect, defaults to 10
+ :type intensity: float
+ :return: The resulting image after applying the filter
+ :rtype: XAImage
+
+ .. versionadded:: 0.1.0
+ """
+ image=Quartz.CIImage.imageWithData_(self.data)
+ filter=Quartz.CIFilter.filterWithName_("CIGaussianBlur")
+ filter.setDefaults()
+ filter.setValue_forKey_(image,"inputImage")
+ filter.setValue_forKey_(intensity,"inputRadius")
+ uncropped=filter.valueForKey_(Quartz.kCIOutputImageKey)
+ returnself.__update_image(uncropped)
+
+
[docs]defreduce_noise(self,noise_level:float=0.02,sharpness:float=0.4)->'XAImage':
+ """Reduces noise in the image by sharpening areas with a luminance delta below the specified noise level threshold.
+
+ :param noise_level: The threshold for luminance changes in an area below which will be considered noise, defaults to 0.02
+ :type noise_level: float
+ :param sharpness: The sharpness of the resulting image, defaults to 0.4
+ :type sharpness: float
+ :return: The resulting image after applying the filter
+ :rtype: XAImage
+
+ .. versionadded:: 0.1.0
+ """
+ image=Quartz.CIImage.imageWithData_(self.data)
+ filter=Quartz.CIFilter.filterWithName_("CINoiseReduction")
+ filter.setDefaults()
+ filter.setValue_forKey_(image,"inputImage")
+ filter.setValue_forKey_(noise_level,"inputNoiseLevel")
+ filter.setValue_forKey_(sharpness,"inputSharpness")
+ uncropped=filter.valueForKey_(Quartz.kCIOutputImageKey)
+ returnself.__update_image(uncropped)
+
+
[docs]defpixellate(self,pixel_size:float=8.0)->'XAImage':
+ """Pixellates the image.
+
+ :param pixel_size: The size of the pixels, defaults to 8.0
+ :type pixel_size: float
+ :return: The resulting image after applying the filter
+ :rtype: XAImage
+
+ .. versionadded:: 0.1.0
+ """
+ image=Quartz.CIImage.imageWithData_(self.data)
+ filter=Quartz.CIFilter.filterWithName_("CIPixellate")
+ filter.setDefaults()
+ filter.setValue_forKey_(image,"inputImage")
+ filter.setValue_forKey_(pixel_size,"inputScale")
+ uncropped=filter.valueForKey_(Quartz.kCIOutputImageKey)
+ returnself.__update_image(uncropped)
+
+
[docs]defoutline(self,threshold:float=0.1)->'XAImage':
+ """Outlines detected edges within the image in black, leaving the rest transparent.
+
+ :param threshold: The threshold to use when separating edge and non-edge pixels. Larger values produce thinner edge lines. Defaults to 0.1
+ :type threshold: float
+ :return: The resulting image after applying the filter
+ :rtype: XAImage
+
+ .. versionadded:: 0.1.0
+ """
+ image=Quartz.CIImage.imageWithData_(self.data)
+ filter=Quartz.CIFilter.filterWithName_("CILineOverlay")
+ filter.setDefaults()
+ filter.setValue_forKey_(image,"inputImage")
+ filter.setValue_forKey_(threshold,"inputThreshold")
+ uncropped=filter.valueForKey_(Quartz.kCIOutputImageKey)
+ returnself.__update_image(uncropped)
+
+
[docs]definvert(self)->'XAImage':
+ """Inverts the color of the image.
+
+ :return: The resulting image after applying the filter
+ :rtype: XAImage
+
+ .. versionadded:: 0.1.0
+ """
+ image=Quartz.CIImage.imageWithData_(self.data)
+ filter=Quartz.CIFilter.filterWithName_("CIColorInvert")
+ filter.setDefaults()
+ filter.setValue_forKey_(image,"inputImage")
+ uncropped=filter.valueForKey_(Quartz.kCIOutputImageKey)
+ returnself.__update_image(uncropped)
+
+
[docs]defsepia(self,intensity:float=1.0)->'XAImage':
+ """Applies a sepia filter to the image; maps all colors of the image to shades of brown.
+
+ :param intensity: The opacity of the sepia effect. A value of 0 will have no impact on the image. Defaults to 1.0
+ :type intensity: float
+ :return: The resulting image after applying the filter
+ :rtype: XAImage
+
+ .. versionadded:: 0.1.0
+ """
+ image=Quartz.CIImage.imageWithData_(self.data)
+ filter=Quartz.CIFilter.filterWithName_("CISepiaTone")
+ filter.setDefaults()
+ filter.setValue_forKey_(image,"inputImage")
+ filter.setValue_forKey_(intensity,"inputIntensity")
+ uncropped=filter.valueForKey_(Quartz.kCIOutputImageKey)
+ returnself.__update_image(uncropped)
+
+
[docs]defvignette(self,intensity:float=1.0)->'XAImage':
+ """Applies vignette shading to the corners of the image.
+
+ :param intensity: The intensity of the vignette effect, defaults to 1.0
+ :type intensity: float
+ :return: The resulting image after applying the filter
+ :rtype: XAImage
+
+ .. versionadded:: 0.1.0
+ """
+ image=Quartz.CIImage.imageWithData_(self.data)
+ filter=Quartz.CIFilter.filterWithName_("CIVignette")
+ filter.setDefaults()
+ filter.setValue_forKey_(image,"inputImage")
+ filter.setValue_forKey_(intensity,"inputIntensity")
+ uncropped=filter.valueForKey_(Quartz.kCIOutputImageKey)
+ returnself.__update_image(uncropped)
+
+
[docs]defdepth_of_field(self,focal_region:Union[tuple[tuple[int,int],tuple[int,int]],None]=None,intensity:float=10.0,focal_region_saturation:float=1.5)->'XAImage':
+ """Applies a depth of field filter to the image, simulating a tilt & shift effect.
+
+ :param focal_region: 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
+ :type focal_region: Union[tuple[tuple[int, int], tuple[int, int]], None]
+ :param intensity: 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
+ :type intensity: float
+ :param focal_region_saturation: Adjusts the saturation of the focial region. Higher values increase saturation. Defaults to 1.5 (1.5x default saturation)
+ :type focal_region_saturation: float
+ :return: The resulting image after applying the filter
+ :rtype: XAImage
+
+ .. versionadded:: 0.1.0
+ """
+ iffocal_regionisNone:
+ center_top=Quartz.CIVector.vectorWithX_Y_(self.size[0]/2,self.size[1]/3)
+ center_bottom=Quartz.CIVector.vectorWithX_Y_(self.size[0]/2,self.size[1]/3*2)
+ focal_region=(center_top,center_bottom)
+ else:
+ point1=Quartz.CIVector.vectorWithX_Y_(focal_region[0])
+ point2=Quartz.CIVector.vectorWithX_Y_(focal_region[1])
+ focal_region=(point1,point2)
+
+ image=Quartz.CIImage.imageWithData_(self.data)
+ filter=Quartz.CIFilter.filterWithName_("CIDepthOfField")
+ filter.setDefaults()
+ filter.setValue_forKey_(image,"inputImage")
+ filter.setValue_forKey_(focal_region[0],"inputPoint0")
+ filter.setValue_forKey_(focal_region[1],"inputPoint1")
+ filter.setValue_forKey_(intensity,"inputRadius")
+ filter.setValue_forKey_(focal_region_saturation,"inputSaturation")
+ uncropped=filter.valueForKey_(Quartz.kCIOutputImageKey)
+ returnself.__update_image(uncropped)
+
+
[docs]defcrystallize(self,crystal_size:float=20.0)->'XAImage':
+ """Applies a crystallization filter to the image. Creates polygon-shaped color blocks by aggregating pixel values.
+
+ :param crystal_size: The radius of the crystals, defaults to 20.0
+ :type crystal_size: float
+ :return: The resulting image after applying the filter
+ :rtype: XAImage
+
+ .. versionadded:: 0.1.0
+ """
+ image=Quartz.CIImage.imageWithData_(self.data)
+ filter=Quartz.CIFilter.filterWithName_("CICrystallize")
+ filter.setDefaults()
+ filter.setValue_forKey_(image,"inputImage")
+ filter.setValue_forKey_(crystal_size,"inputRadius")
+ uncropped=filter.valueForKey_(Quartz.kCIOutputImageKey)
+ returnself.__update_image(uncropped)
+
+
[docs]defcomic(self)->'XAImage':
+ """Applies a comic filter to the image. Outlines edges and applies a color halftone effect.
+
+ :return: The resulting image after applying the filter
+ :rtype: XAImage
+
+ .. versionadded:: 0.1.0
+ """
+ image=Quartz.CIImage.imageWithData_(self.data)
+ filter=Quartz.CIFilter.filterWithName_("CIComicEffect")
+ filter.setDefaults()
+ filter.setValue_forKey_(image,"inputImage")
+ uncropped=filter.valueForKey_(Quartz.kCIOutputImageKey)
+ returnself.__update_image(uncropped)
+
+
[docs]defpointillize(self,point_size:float=20.0)->'XAImage':
+ """Applies a pointillization filter to the image.
+
+ :param crystal_size: The radius of the points, defaults to 20.0
+ :type crystal_size: float
+ :return: The resulting image after applying the filter
+ :rtype: XAImage
+
+ .. versionadded:: 0.1.0
+ """
+ image=Quartz.CIImage.imageWithData_(self.data)
+ filter=Quartz.CIFilter.filterWithName_("CIPointillize")
+ filter.setDefaults()
+ filter.setValue_forKey_(image,"inputImage")
+ filter.setValue_forKey_(point_size,"inputRadius")
+ uncropped=filter.valueForKey_(Quartz.kCIOutputImageKey)
+ returnself.__update_image(uncropped)
+
+
[docs]defbloom(self,intensity:float=0.5)->'XAImage':
+ """Applies a bloom effect to the image. Softens edges and adds a glow.
+
+ :param intensity: The strength of the softening and glow effects, defaults to 0.5
+ :type intensity: float
+ :return: The resulting image after applying the filter
+ :rtype: XAImage
+
+ .. versionadded:: 0.1.0
+ """
+ image=Quartz.CIImage.imageWithData_(self.data)
+ filter=Quartz.CIFilter.filterWithName_("CIBloom")
+ filter.setDefaults()
+ filter.setValue_forKey_(image,"inputImage")
+ filter.setValue_forKey_(intensity,"inputIntensity")
+ uncropped=filter.valueForKey_(Quartz.kCIOutputImageKey)
+ returnself.__update_image(uncropped)
+
+
[docs]defmonochrome(self,color:XAColor,intensity:float=1.0)->'XAImage':
+ """Remaps the colors of the image to shades of the specified color.
+
+ :param color: The color of map the image's colors to
+ :type color: XAColor
+ :param intensity: The strength of recoloring effect. Higher values map colors to darker shades of the provided color. Defaults to 1.0
+ :type intensity: float
+ :return: The resulting image after applying the filter
+ :rtype: XAImage
+
+ .. versionadded:: 0.1.0
+ """
+ ci_color=Quartz.CIColor.alloc().initWithColor_(color.xa_elem)
+ image=Quartz.CIImage.imageWithData_(self.data)
+ filter=Quartz.CIFilter.filterWithName_("CIColorMonochrome")
+ filter.setDefaults()
+ filter.setValue_forKey_(image,"inputImage")
+ filter.setValue_forKey_(ci_color,"inputColor")
+ filter.setValue_forKey_(intensity,"inputIntensity")
+ uncropped=filter.valueForKey_(Quartz.kCIOutputImageKey)
+ returnself.__update_image(uncropped)
+
+
[docs]defbump(self,center:Union[tuple[int,int],None]=None,radius:float=300.0,curvature:float=0.5)->'XAImage':
+ """Creates a concave (inward) or convex (outward) bump at the specified location within the image.
+
+ :param center: The center point of the effect, or None to use the center of the image, defaults to None
+ :type center: Union[tuple[int, int], None]
+ :param radius: The radius of the bump in pixels, defaults to 300.0
+ :type radius: float
+ :param curvature: 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
+ :type curvature: float
+ :return: The resulting image after applying the distortion
+ :rtype: XAImage
+
+ .. versionadded:: 0.1.0
+ """
+ ifcenterisNone:
+ center=Quartz.CIVector.vectorWithX_Y_(self.size[0]/2,self.size[1]/2)
+ else:
+ center=Quartz.CIVector.vectorWithX_Y_(center[0],center[1])
+
+ image=Quartz.CIImage.imageWithData_(self.data)
+ filter=Quartz.CIFilter.filterWithName_("CIBumpDistortion")
+ filter.setDefaults()
+ filter.setValue_forKey_(image,"inputImage")
+ filter.setValue_forKey_(center,"inputCenter")
+ filter.setValue_forKey_(radius,"inputRadius")
+ filter.setValue_forKey_(curvature,"inputScale")
+ uncropped=filter.valueForKey_(Quartz.kCIOutputImageKey)
+ returnself.__update_image(uncropped)
+
+
[docs]defpinch(self,center:Union[tuple[int,int],None]=None,intensity:float=0.5)->'XAImage':
+ """Creates an inward pinch distortion at the specified location within the image.
+
+ :param center: The center point of the effect, or None to use the center of the image, defaults to None
+ :type center: Union[tuple[int, int], None]
+ :param intensity: Controls the scale of the pinch effect. Higher values stretch pixels away from the specified center to a greater degree. Defaults to 0.5
+ :type intensity: float
+ :return: The resulting image after applying the distortion
+ :rtype: XAImage
+
+ .. versionadded:: 0.1.0
+ """
+ ifcenterisNone:
+ center=Quartz.CIVector.vectorWithX_Y_(self.size[0]/2,self.size[1]/2)
+ else:
+ center=Quartz.CIVector.vectorWithX_Y_(center[0],center[1])
+
+ image=Quartz.CIImage.imageWithData_(self.data)
+ filter=Quartz.CIFilter.filterWithName_("CIPinchDistortion")
+ filter.setDefaults()
+ filter.setValue_forKey_(image,"inputImage")
+ filter.setValue_forKey_(center,"inputCenter")
+ filter.setValue_forKey_(intensity,"inputScale")
+ uncropped=filter.valueForKey_(Quartz.kCIOutputImageKey)
+ returnself.__update_image(uncropped)
+
+
[docs]deftwirl(self,center:Union[tuple[int,int],None]=None,radius:float=300.0,angle:float=3.14)->'XAImage':
+ """Creates a twirl distortion by rotating pixels around the specified location within the image.
+
+ :param center: The center point of the effect, or None to use the center of the image, defaults to None
+ :type center: Union[tuple[int, int], None]
+ :param radius: The pixel radius around the centerpoint that defines the area to apply the effect to, defaults to 300.0
+ :type radius: float
+ :param angle: The angle of the twirl in radians, defaults to 3.14
+ :type angle: float
+ :return: The resulting image after applying the distortion
+ :rtype: XAImage
+
+ .. versionadded:: 0.1.0
+ """
+ ifcenterisNone:
+ center=Quartz.CIVector.vectorWithX_Y_(self.size[0]/2,self.size[1]/2)
+ else:
+ center=Quartz.CIVector.vectorWithX_Y_(center[0],center[1])
+
+ image=Quartz.CIImage.imageWithData_(self.data)
+ filter=Quartz.CIFilter.filterWithName_("CITwirlDistortion")
+ filter.setDefaults()
+ filter.setValue_forKey_(image,"inputImage")
+ filter.setValue_forKey_(center,"inputCenter")
+ filter.setValue_forKey_(radius,"inputRadius")
+ filter.setValue_forKey_(angle,"inputAngle")
+ uncropped=filter.valueForKey_(Quartz.kCIOutputImageKey)
+ returnself.__update_image(uncropped)
+
+
[docs]defauto_enhance(self,correct_red_eye:bool=False,crop_to_features:bool=False,correct_rotation:bool=False)->'XAImage':
+ """Attempts to enhance the image by applying suggested filters.
+
+ :param correct_red_eye: Whether to attempt red eye removal, defaults to False
+ :type correct_red_eye: bool, optional
+ :param crop_to_features: Whether to crop the image to focus on the main features with it, defaults to False
+ :type crop_to_features: bool, optional
+ :param correct_rotation: Whether attempt perspective correction by rotating the image, defaults to False
+ :type correct_rotation: bool, optional
+ :return: The resulting image after applying the enchantments
+ :rtype: XAImage
+
+ .. versionadded:: 0.1.0
+ """
+ ci_image=Quartz.CIImage.imageWithData_(self.data)
+ options={
+ Quartz.kCIImageAutoAdjustRedEye:correct_red_eye,
+ Quartz.kCIImageAutoAdjustCrop:crop_to_features,
+ Quartz.kCIImageAutoAdjustLevel:correct_rotation
+ }
+ enhancements=ci_image.autoAdjustmentFiltersWithOptions_(options)
+ print(enhancements)
+ forfilterinenhancements:
+ filter.setValue_forKey_(ci_image,"inputImage")
+ ci_image=filter.outputImage()
+ returnself.__update_image(ci_image)
[docs]defrotate(self,degrees:float)->'XAImage':
+ """Rotates the image clockwise by the specified number of degrees.
+
+ :param degrees: The number of degrees to rotate the image by
+ :type degrees: float
+ :return: The image object, modifications included
+ :rtype: XAImage
+
+ .. versionadded:: 0.1.0
+ """
+ sinDegrees=abs(math.sin(degrees*math.pi/180.0))
+ cosDegrees=abs(math.cos(degrees*math.pi/180.0))
+ newSize=Quartz.CGSizeMake(self.size[1]*sinDegrees+self.size[0]*cosDegrees,self.size[0]*sinDegrees+self.size[1]*cosDegrees)
+ rotated_image=AppKit.NSImage.alloc().initWithSize_(newSize)
+
+ imageBounds=Quartz.CGRectMake((newSize.width-self.size[0])/2,(newSize.height-self.size[1])/2,self.size[0],self.size[1])
+
+ transform=AppKit.NSAffineTransform.alloc().init()
+ transform.translateXBy_yBy_(newSize.width/2,newSize.height/2)
+ transform.rotateByDegrees_(degrees)
+ transform.translateXBy_yBy_(-newSize.width/2,-newSize.height/2)
+
+ rotated_image.lockFocus()
+ transform.concat()
+ self.xa_elem.drawInRect_fromRect_operation_fraction_(imageBounds,Quartz.CGRectZero,AppKit.NSCompositingOperationCopy,1.0)
+ rotated_image.unlockFocus()
+ self.xa_elem=rotated_image
+ self.modified=True
+ returnself
+
+
[docs]defcrop(self,size:tuple[int,int],corner:Union[tuple[int,int],None]=None)->'XAImage':
+ """Crops the image to the specified dimensions.
+
+ :param size: The width and height of the resulting image
+ :type size: tuple[int, int]
+ :param corner: The bottom-left corner location from which to crop the image, or None to use (0, 0), defaults to None
+ :type corner: Union[tuple[int, int], None]
+ :return: The image object, modifications included
+ :rtype: XAImage
+
+ .. versionadded:: 0.1.0
+ """
+ ifcornerisNone:
+ # No corner provided -- use (0,0) by default
+ corner=(0,0)
+
+ cropped_image=AppKit.NSImage.alloc().initWithSize_(AppKit.NSMakeSize(size[0],size[1]))
+ imageBounds=AppKit.NSMakeRect(corner[0],corner[1],self.size[0],self.size[1])
+
+ cropped_image.lockFocus()
+ self.xa_elem.drawInRect_(imageBounds)
+ cropped_image.unlockFocus()
+ self.xa_elem=cropped_image
+ self.modified=True
+ returnself
+
+
[docs]defscale(self,scale_factor_x:float,scale_factor_y:Union[float,None]=None)->'XAImage':
+ """Scales the image by the specified horizontal and vertical factors.
+
+ :param scale_factor_x: The factor by which to scale the image in the X dimension
+ :type scale_factor_x: float
+ :param scale_factor_y: The factor by which to scale the image in the Y dimension, or None to match the horizontal factor, defaults to None
+ :type scale_factor_y: Union[float, None]
+ :return: The image object, modifications included
+ :rtype: XAImage
+
+ .. versionadded:: 0.1.0
+ """
+ ifscale_factor_yisNone:
+ scale_factor_y=scale_factor_x
+
+ scaled_image=AppKit.NSImage.alloc().initWithSize_(AppKit.NSMakeSize(self.size[0]*scale_factor_x,self.size[1]*scale_factor_y))
+ imageBounds=AppKit.NSMakeRect(0,0,self.size[0],self.size[1])
+
+ transform=AppKit.NSAffineTransform.alloc().init()
+ transform.scaleXBy_yBy_(scale_factor_x,scale_factor_y)
+
+ scaled_image.lockFocus()
+ transform.concat()
+ self.xa_elem.drawInRect_fromRect_operation_fraction_(imageBounds,Quartz.CGRectZero,AppKit.NSCompositingOperationCopy,1.0)
+ scaled_image.unlockFocus()
+ self.xa_elem=scaled_image
+ self.modified=True
+ returnself
+
+
[docs]defpad(self,horizontal_border_width:int=50,vertical_border_width:int=50,pad_color:Union[XAColor,None]=None)->'XAImage':
+ """Pads the image with the specified color; adds a border around the image with the specified vertical and horizontal width.
+
+ :param horizontal_border_width: The border width, in pixels, in the x-dimension, defaults to 50
+ :type horizontal_border_width: int
+ :param vertical_border_width: The border width, in pixels, in the y-dimension, defaults to 50
+ :type vertical_border_width: int
+ :param pad_color: The color of the border, or None for a white border, defaults to None
+ :type pad_color: Union[XAColor, None]
+ :return: The image object, modifications included
+ :rtype: XAImage
+
+ .. versionadded:: 0.1.0
+ """
+ ifpad_colorisNone:
+ # No color provided -- use white by default
+ pad_color=XAColor.white()
+
+ new_width=self.size[0]+horizontal_border_width*2
+ new_height=self.size[1]+vertical_border_width*2
+ color_swatch=pad_color.make_swatch(new_width,new_height)
+
+ color_swatch.xa_elem.lockFocus()
+ bounds=AppKit.NSMakeRect(horizontal_border_width,vertical_border_width,self.size[0],self.size[1])
+ self.xa_elem.drawInRect_(bounds)
+ color_swatch.xa_elem.unlockFocus()
+ self.xa_elem=color_swatch.xa_elem
+ self.modified=True
+ returnself
+
+
[docs]defoverlay_image(self,image:'XAImage',location:Union[tuple[int,int],None]=None,size:Union[tuple[int,int],None]=None)->'XAImage':
+ """Overlays an image on top of this image, at the specified location, with the specified size.
+
+ :param image: The image to overlay on top of this image
+ :type image: XAImage
+ :param location: The bottom-left point of the overlaid image in the result, or None to use the bottom-left point of the background image, defaults to None
+ :type location: Union[tuple[int, int], None]
+ :param size: 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 the background image, defaults to None
+ :type size: Union[tuple[int, int], None]
+ :return: The image object, modifications included
+ :rtype: XAImage
+
+ .. versionadded:: 0.1.0
+ """
+ iflocationisNone:
+ # No location provided -- use the bottom-left point of the background image by default
+ location=(0,0)
+
+ ifsizeisNone:
+ # No dimensions provided -- use size of overlay image by default
+ size=image.size
+ elifsize==(-1,-1):
+ # Use remaining width/height of background image
+ size=(self.size[0]-location[0],self.size[1]-location[1])
+ elifsize[0]==-1:
+ # Use remaining width of background image + provided height
+ size=(self.size[0]-location[0],size[1])
+ elifsize[1]==-1:
+ # Use remaining height of background image + provided width
+ size=(size[1],self.size[1]-location[1])
+
+ self.xa_elem.lockFocus()
+ bounds=AppKit.NSMakeRect(location[0],location[1],size[0],size[1])
+ image.xa_elem.drawInRect_(bounds)
+ self.xa_elem.unlockFocus()
+ self.modified=True
+ returnself.xa_elem
+
+
[docs]defoverlay_text(self,text:str,location:Union[tuple[int,int],None]=None,font_size:float=12,font_color:Union[XAColor,None]=None)->'XAImage':
+ """Overlays text of the specified size and color at the provided location within the image.
+
+ :param text: The text to overlay onto the image
+ :type text: str
+ :param location: The bottom-left point of the start of the text, or None to use (5, 5), defaults to None
+ :type location: Union[tuple[int, int], None]
+ :param font_size: The font size, in pixels, of the text, defaults to 12
+ :type font_size: float
+ :param font_color: The color of the text, or None to use black, defaults to None
+ :type font_color: XAColor
+ :return: The image object, modifications included
+ :rtype: XAImage
+
+ .. versionadded:: 0.1.0
+ """
+ iflocationisNone:
+ # No location provided -- use (5, 5) by default
+ location=(5,5)
+
+ iffont_colorisNone:
+ # No color provided -- use black by default
+ font_color=XAColor.black()
+
+ font=AppKit.NSFont.userFontOfSize_(font_size)
+ textRect=Quartz.CGRectMake(location[0],0,self.size[0]-location[0],location[1])
+ attributes={
+ AppKit.NSFontAttributeName:font,
+ AppKit.NSForegroundColorAttributeName:font_color.xa_elem
+ }
+
+ self.xa_elem.lockFocus()
+ AppKit.NSString.alloc().initWithString_(text).drawInRect_withAttributes_(textRect,attributes)
+ self.xa_elem.unlockFocus()
+ self.modified=True
+ returnself
+
+
[docs]defextract_text(self)->list[str]:
+ """Extracts and returns all visible text in the image.
+
+ :return: The array of extracted text strings
+ :rtype: 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', ...]
+
+ .. versionadded:: 0.1.0
+ """
+ # Prepare CGImage
+ ci_image=Quartz.CIImage.imageWithData_(self.data)
+ context=Quartz.CIContext.alloc().initWithOptions_(None)
+ img=context.createCGImage_fromRect_(ci_image,ci_image.extent())
+
+ # Handle request completion
+ extracted_strings=[]
+ defrecognize_text_handler(request,error):
+ observations=request.results()
+ forobservationinobservations:
+ recognized_strings=observation.topCandidates_(1)[0].string()
+ extracted_strings.append(recognized_strings)
+
+ # Perform request and return extracted text
+ request=Vision.VNRecognizeTextRequest.alloc().initWithCompletionHandler_(recognize_text_handler)
+ request_handler=Vision.VNImageRequestHandler.alloc().initWithCGImage_options_(img,None)
+ request_handler.performRequests_error_([request],None)
+ returnextracted_strings
[docs]defsave(self,file_path:Union[XAPath,str,None]=None):
+ """Saves the image to a file on the disk. Saves to the original file (if there was one) by default.
+
+ :param file_path: The path at which to save the image file. Any existing file at that location will be overwritten, defaults to None
+ :type file_path: Union[XAPath, str, None]
+
+ .. versionadded:: 0.1.0
+ """
+ iffile_pathisNoneandself.fileisnotNone:
+ file_path=self.file.path
+ elifisinstance(file_path,XAPath):
+ file_path=file_path.path
+ fm=AppKit.NSFileManager.defaultManager()
+ fm.createFileAtPath_contents_attributes_(file_path,self.xa_elem.TIFFRepresentation(),None)
+
+
[docs]defget_clipboard_representation(self)->AppKit.NSImage:
+ """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.
+
+ :return: The raw NSImage object for this XAIMage
+ :rtype: AppKit.NSImage
+
+ .. versionadded:: 0.1.0
+ """
+ returnself.xa_elem
+
+
+
+
+
[docs]classXASoundList(XAList,XAClipboardCodable):
+ """A wrapper around lists of sounds that employs fast enumeration techniques.
+
+ .. versionadded:: 0.1.0
+ """
+ def__init__(self,properties:dict,filter:Union[dict,None]=None):
+ super().__init__(properties,XASound,filter)
+
+
[docs]defget_clipboard_representation(self)->list[Union[AppKit.NSSound,AppKit.NSURL,str]]:
+ """Gets a clipboard-codable representation of each sound in the list.
+
+ When the clipboard content is set to a list of sounds, each sound's raw sound data, its associated file URL, and its file path string are added to the clipboard.
+
+ :return: The clipboard-codable form of the sound
+ :rtype: Any
+
+ .. versionadded:: 0.1.0
+ """
+ return[self.xa_elem,self.file.xa_elem,self.file.xa_elem.path()]
+
+
[docs]classXASound(XAObject,XAClipboardCodable):
+ """A class for playing and interacting with audio files and data.
+
+ .. versionadded:: 0.0.1
+ """
+ def__init__(self,sound_reference:Union[str,XAURL,XAPath]):
+ self.file=None
+
+ ifisinstance(sound_reference,str):
+ # Sound reference is a string
+ if"://"insound_reference:
+ # Sound reference is a URL
+ self.file=XAURL(sound_reference)
+ sound_reference=self.file.xa_elem
+ if"/"insound_reference:
+ # Sound reference is a file path
+ self.file=XAPath(sound_reference)
+ sound_reference=self.file.xa_elem
+ else:
+ # Sound reference is the name of a default sound
+ self.file=XAPath("/System/Library/Sounds/"+sound_reference+".aiff")
+ sound_reference=self.file.xa_elem
+ elifisinstance(sound_reference,dict):
+ # Sound reference comes from XAList
+ sound_reference=sound_reference["element"]
+ # Sound reference is a string
+ ifisinstance(sound_reference,str):
+ if"://"insound_reference:
+ # Sound reference is a URL
+ self.file=XAURL(sound_reference)
+ sound_reference=self.file.xa_elem
+ if"/"insound_reference:
+ # Sound reference is a file path
+ self.file=XAPath(sound_reference)
+ sound_reference=self.file.xa_elem
+ else:
+ # Sound reference is the name of a default sound
+ self.file=XAPath("/System/Library/Sounds/"+sound_reference+".aiff")
+ sound_reference=XAPath(self.file)
+ elifisinstance(sound_reference,XAPath):
+ # Sound reference is an XAPath object
+ self.file=sound_reference
+ sound_reference=sound_reference.xa_elem
+ elifisinstance(sound_reference,XAURL):
+ # Sound reference is an XAURL object
+ self.file=sound_reference
+ sound_reference=sound_reference
+ elifisinstance(sound_reference,XASound):
+ self.file=sound_reference.file
+ sound_reference=sound_reference.xa_elem
+
+ ifisinstance(sound_reference,AVFoundation.AVAudioFile):
+ # Sound reference is an NSSound object
+ self.xa_elem=sound_reference
+
+ self.duration:float#: The duration of the sound in seconds
+
+ self.__audio_file=AVFoundation.AVAudioFile.alloc().initForReading_error_(self.file.xa_elemifself.fileisnotNoneelseNone,None)[0]
+
+ self.__audio_engine=AVFoundation.AVAudioEngine.alloc().init()
+ self.__player_node=AVFoundation.AVAudioPlayerNode.alloc().init()
+ self.__audio_engine.attachNode_(self.__player_node)
+
+ self.__audio_engine.connect_to_format_(self.__player_node,self.__audio_engine.mainMixerNode(),self.__audio_file.processingFormat())
+
+ self.__player_node.stop()
+ self.__audio_engine.stop()
+
+ self.xa_elem=self.__audio_file
+
+ @property
+ defnum_sample_frames(self)->int:
+ """The number of sample frames in the audio file.
+
+ .. versionadded:: 0.1.0
+ """
+ returnself.xa_elem.length()
+
+ @property
+ defsample_rate(self)->float:
+ """The sample rate for the sound format, in hertz.
+
+ .. versionadded:: 0.1.0
+ """
+ returnself.xa_elem.processingFormat().sampleRate()
+
+ @property
+ defduration(self)->float:
+ """The duration of the sound in seconds.
+
+ .. versionadded:: 0.1.0
+ """
+ returnself.num_sample_frames/self.sample_rate
+
+
[docs]defopen(*sound_references:Union[str,XAPath,list[Union[str,XAPath]]])->Union['XASound',XASoundList]:
+ """Initializes one or more sounds from files.
+
+ :param sound_references: The sound(s) to open
+ :type sound_references: Union[str, XAPath, list[Union[str, XAPath]]]
+ :return: The newly created sound object, or a list of sound objects
+ :rtype: Union[XASound, XASoundList]
+
+ .. versionadded:: 0.1.0
+ """
+ iflen(sound_references)==1:
+ sound_references=sound_references[0]
+
+ ifisinstance(sound_references,list)orisinstance(sound_references,tuple):
+ returnXASoundList({"element":sound_references})
+ else:
+ returnXASound(sound_references)
[docs]defplay(self)->Self:
+ """Plays the sound from the beginning.
+
+ Audio playback runs in a separate thread. For the sound the play properly, you must keep the main thread alive over the duration of the desired playback.
+
+ :return: A reference to this sound object.
+ :rtype: Self
+
+ :Example:
+
+ >>> import PyXA
+ >>> import time
+ >>> glass_sound = PyXA.sound("Glass")
+ >>> glass_sound.play()
+ >>> time.sleep(glass_sound.duration)
+
+ .. seealso:: :func:`pause`, :func:`stop`
+
+ .. versionadded:: 0.0.1
+ """
+ defplay_sound(self):
+ self.__player_node.scheduleFile_atTime_completionHandler_(self.xa_elem,None,None)
+ self.__audio_engine.startAndReturnError_(None)
+ self.__player_node.play()
+ whileself.__player_node.isPlaying():
+ AppKit.NSRunLoop.currentRunLoop().runUntilDate_(datetime.now()+timedelta(seconds=0.1))
+
+ self._spawn_thread(play_sound,[self])
+ returnself
[docs]defresume(self)->Self:
+ """Plays the sound starting from the time it was last paused at.
+
+ Audio playback runs in a separate thread. For the sound the play properly, you must keep the main thread alive over the duration of the desired playback.
+
+ :return: A reference to this sound object.
+ :rtype: Self
+
+ :Example:
+
+ >>> import PyXA
+ >>> glass_sound = PyXA.sound("Glass")
+ >>> glass_sound.resume()
+
+ .. seealso:: :func:`pause`, :func:`play`
+
+ .. versionadded:: 0.0.1
+ """
+ defplay_sound(self):
+ self.__player_node.scheduleFile_atTime_completionHandler_(self.xa_elem,None,None)
+ self.__audio_engine.startAndReturnError_(None)
+ self.__player_node.play()
+ whileself.__player_node.isPlaying():
+ AppKit.NSRunLoop.currentRunLoop().runUntilDate_(datetime.now()+timedelta(seconds=0.1))
+
+ self._spawn_thread(play_sound,[self])
+ returnself
+
+
[docs]defstop(self)->'XASound':
+ """Stops playback of the sound and rewinds it to the beginning.
+
+ :return: A reference to this sound object.
+ :rtype: XASound
+
+ :Example:
+
+ >>> import PyXA
+ >>> glass_sound = PyXA.sound("Glass")
+ >>> glass_sound.stop()
+
+ .. seealso:: :func:`pause`, :func:`play`
+
+ .. versionadded:: 0.0.1
+ """
+ self.__audio_engine.stop()
+ returnself
+
+
[docs]defset_volume(self,volume:float)->Self:
+ """Sets the volume of the sound.
+
+ :param volume: The desired volume of the sound in the range [0.0, 1.0].
+ :type volume: int
+ :return: A reference to this sound object.
+ :rtype: Self
+
+ :Example:
+
+ >>> import PyXA
+ >>> glass_sound = PyXA.sound("Glass")
+ >>> glass_sound.set_volume(1.0)
+
+ .. seealso:: :func:`volume`
+
+ .. versionadded:: 0.0.1
+ """
+ self.__audio_engine.mainMixerNode().setOutputVolume_(volume)
+ returnself
+
+
[docs]defvolume(self)->float:
+ """Returns the current volume of the sound.
+
+ :return: The volume level of the sound.
+ :rtype: int
+
+ :Example:
+
+ >>> import PyXA
+ >>> glass_sound = PyXA.sound("Glass")
+ >>> print(glass_sound.volume())
+ 1.0
+
+ .. seealso:: :func:`set_volume`
+
+ .. versionadded:: 0.0.1
+ """
+ returnself.__audio_engine.mainMixerNode().volume()
+
+
[docs]defloop(self,times:int)->Self:
+ """Plays the sound the specified number of times.
+
+ Audio playback runs in a separate thread. For the sound the play properly, you must keep the main thread alive over the duration of the desired playback.
+
+ :param times: The number of times to loop the sound.
+ :type times: int
+ :return: A reference to this sound object.
+ :rtype: Self
+
+ :Example:
+
+ >>> import PyXA
+ >>> import time
+ >>> glass_sound = PyXA.sound("Glass")
+ >>> glass_sound.loop(10)
+ >>> time.sleep(glass_sound.duration * 10)
+
+ .. versionadded:: 0.0.1
+ """
+ defplay_sound():
+ num_plays=0
+ whilenum_plays<times:
+ sound=XASound(self.file)
+ sound.play()
+ num_plays+=1
+ time.sleep(self.duration)
+
+ self._spawn_thread(play_sound)
+ returnself
+
+
[docs]deftrim(self,start_time:float,end_time:float)->Self:
+ """Trims the sound to the specified start and end time, in seconds.
+
+ This will create a momentary sound data file in the current working directory for storing the intermediary trimmed sound data.
+
+ :param start_time: The start time in seconds
+ :type start_time: float
+ :param end_time: The end time in seconds
+ :type end_time: float
+ :return: The updated sound object
+ :rtype: Self
+
+ .. versionadded:: 0.1.0
+ """
+ # Clear the temp data path
+ file_path="sound_data_tmp.m4a"
+ ifos.path.exists(file_path):
+ AppKit.NSFileManager.defaultManager().removeItemAtPath_error_(file_path,None)
+
+ # Configure the export session
+ asset=AVFoundation.AVAsset.assetWithURL_(self.file.xa_elem)
+ export_session=AVFoundation.AVAssetExportSession.exportSessionWithAsset_presetName_(asset,AVFoundation.AVAssetExportPresetAppleM4A)
+
+ start_time=CoreMedia.CMTimeMake(start_time*100,100)
+ end_time=CoreMedia.CMTimeMake(end_time*100,100)
+ time_range=CoreMedia.CMTimeRangeFromTimeToTime(start_time,end_time);
+
+ export_session.setTimeRange_(time_range)
+ export_session.setOutputURL_(XAPath(file_path).xa_elem)
+ export_session.setOutputFileType_(AVFoundation.AVFileTypeAppleM4A)
+
+ # Export to file path
+ waiting=False
+ defhandler():
+ nonlocalwaiting
+ waiting=True
+
+ export_session.exportAsynchronouslyWithCompletionHandler_(handler)
+
+ whilenotwaiting:
+ time.sleep(0.01)
+
+ # Load the sound file back into active memory
+ self.__audio_file=AVFoundation.AVAudioFile.alloc().initForReading_error_(XAPath(file_path).xa_elem,None)[0]
+ self.xa_elem=self.__audio_file
+ AppKit.NSFileManager.defaultManager().removeItemAtPath_error_(file_path,None)
+ returnself
+
+
[docs]defsave(self,file_path:Union[XAPath,str]):
+ """Saves the sound to the specified file path.
+
+ :param file_path: The path to save the sound to
+ :type file_path: Union[XAPath, str]
+
+ .. versionadded:: 0.1.0
+ """
+ ifisinstance(file_path,str):
+ file_path=XAPath(file_path)
+
+ # Configure the export session
+ asset=AVFoundation.AVAsset.assetWithURL_(self.file.xa_elem)
+ export_session=AVFoundation.AVAssetExportSession.exportSessionWithAsset_presetName_(asset,AVFoundation.AVAssetExportPresetAppleM4A)
+
+ start_time=CoreMedia.CMTimeMake(0,100)
+ end_time=CoreMedia.CMTimeMake(self.duration*100,100)
+ time_range=CoreMedia.CMTimeRangeFromTimeToTime(start_time,end_time);
+
+ export_session.setTimeRange_(time_range)
+ export_session.setOutputURL_(file_path.xa_elem)
+ # export_session.setOutputFileType_(AVFoundation.AVFileTypeAppleM4A)
+
+ # Export to file path
+ waiting=False
+ defhandler():
+ nonlocalwaiting
+ waiting=True
+
+ export_session.exportAsynchronouslyWithCompletionHandler_(handler)
+
+ whilenotwaiting:
+ time.sleep(0.01)
+
+
[docs]defget_clipboard_representation(self)->list[Union[AppKit.NSSound,AppKit.NSURL,str]]:
+ """Gets a clipboard-codable representation of the sound.
+
+ When the clipboard content is set to a sound, the raw sound data, the associated file URL, and the path string of the file are added to the clipboard.
+
+ :return: The clipboard-codable form of the sound
+ :rtype: Any
+
+ .. versionadded:: 0.0.8
+ """
+ return[self.xa_elem,self.file.xa_elem,self.file.xa_elem.path()]
+
+
+
+
[docs]classXAVideo(XAObject):
+ """A class for interacting with video files and data.
+
+ .. versionadded:: 0.1.0
+ """
+ def__init__(self,video_reference:Union[str,XAURL,XAPath]):
+ ifisinstance(video_reference,str):
+ # References is to some kind of path or URL
+ if"://"invideo_reference:
+ video_reference=XAURL(video_reference)
+ else:
+ video_reference=XAPath(video_reference)
+
+ self.xa_elem=AVFoundation.AVURLAsset.alloc().initWithURL_options_(video_reference.xa_elem,{AVFoundation.AVURLAssetPreferPreciseDurationAndTimingKey:objc.YES})
+
+
[docs]defshow_in_quicktime(self):
+ """Shows the video in QuickTime Player.
+
+ This will create a momentary video data file in the current working directory to store intermediary video data.
+
+ .. versionadded:: 0.1.0
+ """
+ self.save("video-data-tmp.mp4")
+
+ video_url=XAPath(os.getcwd()+"/video-data-tmp.mp4").xa_elem
+ quicktime_url=XAPath("/System/Applications/QuickTime Player.app").xa_elem
+ AppKit.NSWorkspace.sharedWorkspace().openURLs_withApplicationAtURL_configuration_completionHandler_([video_url],quicktime_url,None,None)
+ time.sleep(1)
+
+ AppKit.NSFileManager.defaultManager().removeItemAtPath_error_(video_url.path(),None)
+
+
[docs]defsave(self,file_path:Union[XAPath,str]):
+ """Saves the video at the specified file path.
+
+ :param file_path: The path to save the video at
+ :type file_path: Union[XAPath, str]
+
+ .. versionadded:: 0.1.0
+ """
+ ifisinstance(file_path,str):
+ file_path=XAPath(file_path)
+
+ # Configure the export session
+ export_session=AVFoundation.AVAssetExportSession.exportSessionWithAsset_presetName_(self.xa_elem,AVFoundation.AVAssetExportPresetHighestQuality)
+
+ start_time=CoreMedia.CMTimeMake(0,100)
+ end_time=CoreMedia.CMTimeMake(self.xa_elem.duration().value*self.xa_elem.duration().timescale,100)
+ time_range=CoreMedia.CMTimeRangeFromTimeToTime(start_time,end_time);
+
+ export_session.setTimeRange_(time_range)
+ export_session.setOutputURL_(file_path.xa_elem)
+
+ # Export to file path
+ waiting=False
+ defhandler():
+ nonlocalwaiting
+ waiting=True
+
+ export_session.exportAsynchronouslyWithCompletionHandler_(handler)
+
+ whilenotwaiting:
+ time.sleep(0.01)
+
+
+
+
+
+
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/docs/_modules/PyXA/XABase.html b/docs/_modules/PyXA/XABase.html
index 7616a55..9fb5edc 100644
--- a/docs/_modules/PyXA/XABase.html
+++ b/docs/_modules/PyXA/XABase.html
@@ -3,7 +3,7 @@
- PyXA.XABase — PyXA 0.0.9 documentation
+ PyXA.XABase — PyXA 0.1.0 documentation
@@ -14,7 +14,9 @@
+
+
@@ -73,36 +75,47 @@
raiseerrorreturnvalue
- def_new_element(self,obj:AppKit.NSObject,obj_class:type='XAObject',*args:List[Any])->'XAObject':
+ def_new_element(self,obj:AppKit.NSObject,obj_class:type='XAObject',*args:list[Any])->'XAObject':"""Wrapper for creating a new PyXA object. :param folder_obj: The Objective-C representation of an object.
@@ -185,23 +224,22 @@
Source code for PyXA.XABase
"""properties={"parent":self,
- "appspace":self.xa_apsp,
- "workspace":self.xa_wksp,
+ "appspace":self._xa_apsp,
+ "workspace":getattr(self,"xa_wksp",None),"element":obj,
- "appref":self.xa_aref,
- "system_events":self.xa_sevt,
+ "appref":getattr(self,"xa_aref",None),}returnobj_class(properties,*args)
- def_spawn_thread(self,function:Callable[...,Any],args:Union[List[Any],None]=None,kwargs:Union[List[Any],None]=None,daemon:bool=True)->threading.Thread:
+ def_spawn_thread(self,function:Callable[...,Any],args:Union[list[Any],None]=None,kwargs:Union[list[Any],None]=None,daemon:bool=True)->threading.Thread:"""Spawns a new thread running the specified function. :param function: The function to run in the new thread :type function: Callable[..., Any] :param args: Arguments to pass to the function
- :type args: List[Any]
+ :type args: list[Any] :param kwargs: Keyword arguments to pass to the function
- :type kwargs: List[Any]
+ :type kwargs: list[Any] :param daemon: Whether the thread should be a daemon thread, defaults to True :type daemon: bool, optional :return: The thread object
@@ -292,2447 +330,7218 @@
[docs]defset_scriptable_property(self,property_name:str,value:Any)->'XAObject':
+ """Updates the value of a single scriptable element property of the scripting element associated with this object.
+ :param property: The name of the property to assign a new value to.
+ :type property: str
+ :param value: The value to assign to the specified property.
+ :type value: Any
+ :return: A reference to this PyXA object.
+ :rtype: XAObject
-
[docs]classAppleScript(XAObject):
- """A class for constructing and executing AppleScript scripts.
+ .. versionadded:: 0.1.0
+ """
+ parts=property_name.split("_")
+ titled_parts=[part.title()forpartinparts[1:]]
+ property_name=parts[0]+"".join(titled_parts)
+ self.xa_scel.setValue_forKey_(value,property_name)
+ returnself
[docs]classXAApplication(XAObject,XAClipboardCodable):
+ """A general application class for both officially scriptable and non-scriptable applications.
+
+ .. seealso:: :class:`XASBApplication`, :class:`XAWindow`
+
+ .. versionadded:: 0.0.1 """
- def__init__(self,script:Union[str,List[str],None]=None):
- """Creates a new AppleScript object.
+ def__init__(self,properties):
+ super().__init__(properties)
+ self.xa_wcls=XAWindow
+ self.__xa_prcs=None
- :param script: A string or list of strings representing lines of AppleScript code, or the path to a script plaintext file, defaults to None
- :type script: Union[str, List[str], None], optional
+ self.xa_apsc:appscript.GenericApp
- .. versionadded:: 0.0.5
- """
- self.script:List[str]#: The lines of AppleScript code contained in the script
- self.last_result:Any#: The return value of the last execution of the script
- self.file_path:XAPath#: The file path of this script, if one exists
+ @property
+ defxa_prcs(self):
+ ifself.__xa_prcs==None:
+ predicate=AppKit.NSPredicate.predicateWithFormat_("displayedName == %@",self.xa_elem.localizedName())
+ process=self.xa_sevt.processes().filteredArrayUsingPredicate_(predicate)[0]
+
+ properties={
+ "parent":self,
+ "appspace":self._xa_apsp,
+ "workspace":self.xa_wksp,
+ "element":process,
+ "appref":self.xa_aref,
+ "window_class":self.xa_wcls
+ }
+ self.__xa_prcs=XAProcess(properties)
+ returnself.__xa_prcs
- ifisinstance(script,str):
- ifscript.startswith("/"):
- withopen(script,'r')asf:
- script=f.readlines()
- else:
- self.script=[script]
- elifisinstance(script,list):
- self.script=script
- elifscript==None:
- self.script=[]
+ def__getattr__(self,attr):
+ ifattrinself.__dict__:
+ # If possible, use PyXA attribute
+ returnsuper().__getattribute__(attr)
+ else:
+ # Otherwise, fall back to appscript
+ returngetattr(self.xa_apsc,attr)@property
- deflast_result(self)->Any:
- returnself.__last_result
+ defxa_apsc(self)->appscript.GenericApp:
+ returnappscript.app(self.bundle_url.path())@property
- deffile_path(self)->'XAPath':
- returnself.__file_path
+ defbundle_identifier(self)->str:
+ """The bundle identifier for the application.
-
[docs]defadd(self,script:Union[str,List[str],'AppleScript']):
- """Adds the supplied string, list of strings, or script as a new line entry in the script.
+ .. versionadded:: 0.0.1
+ """
+ returnself.xa_elem.bundleIdentifier()
- :param script: The script to append to the current script string.
- :type script: Union[str, List[str], AppleScript]
+ @property
+ defbundle_url(self)->str:
+ """The file URL of the application bundle.
- :Example:
+ .. versionadded:: 0.0.1
+ """
+ returnself.xa_elem.bundleURL()
- >>> import PyXA
- >>> script = PyXA.AppleScript("tell application \"Safari\"")
- >>> script.add("print the document of window 1")
- >>> script.add("end tell")
- >>> script.run()
+ @property
+ defexecutable_url(self)->str:
+ """The file URL of the application's executable.
- .. versionadded:: 0.0.5
+ .. versionadded:: 0.0.1 """
- ifisinstance(script,str):
- self.script.append(script)
- elifisinstance(script,list):
- self.script.extend(script)
- elifisinstance(script,AppleScript):
- self.script.extend(script.script)
+ returnself.xa_elem.executableURL()
-
[docs]definsert(self,index:int,script:Union[str,List[str],'AppleScript']):
- """Inserts the supplied string, list of strings, or script as a line entry in the script starting at the given line index.
+ @property
+ deffrontmost(self)->bool:
+ """Whether the application is the active application.
- :param index: The line index to begin insertion at
- :type index: int
- :param script: The script to insert into the current script
- :type script: Union[str, List[str], AppleScript]
+ .. versionadded:: 0.0.1
+ """
+ returnself.xa_elem.isActive()
- :Example:
+ @frontmost.setter
+ deffrontmost(self,frontmost:bool):
+ iffrontmostisTrue:
+ self.xa_elem.activateWithOptions_(AppKit.NSApplicationActivateIgnoringOtherApps)
- >>> import PyXA
- >>> script = PyXA.AppleScript.load("/Users/exampleUser/Downloads/Test.scpt")
- >>> script.insert(1, "activate")
- >>> script.run()
+ @property
+ deflaunch_date(self)->datetime:
+ """The date and time that the application was launched.
- .. versionadded:: 0.0.9
+ .. versionadded:: 0.0.1 """
- ifisinstance(script,str):
- self.script.insert(index,script)
- elifisinstance(script,list):
- forlineinscript:
- self.script.insert(index,line)
- index+=1
- elifisinstance(script,AppleScript):
- forlineinscript.script:
- self.script.insert(index,line)
- index+=1
+ returnself.xa_elem.launchDate()
-
[docs]defpop(self,index:int=-1)->str:
- """Removes the line at the given index from the script.
+ @property
+ deflocalized_name(self)->str:
+ """The application's name.
- :param index: The index of the line to remove
- :type index: int
- :return: The text of the removed line
- :rtype: str
+ .. versionadded:: 0.0.1
+ """
+ returnself.xa_elem.localizedName()
- :Example:
+ @property
+ defowns_menu_bar(self)->bool:
+ """Whether the application owns the top menu bar.
- >>> import PyXA
- >>> script = PyXA.AppleScript.load("/Users/exampleUser/Downloads/Test.scpt")
- >>> print(script.pop(1))
- get chats
+ .. versionadded:: 0.0.1
+ """
+ returnself.xa_elem.ownsMenuBar()
- .. versionadded:: 0.0.9
+ @property
+ defprocess_identifier(self)->str:
+ """The process identifier for the application instance.
+
+ .. versionadded:: 0.0.1 """
- returnself.script.pop(index)
+ returnself.xa_elem.processIdentifier()
-
[docs]defload(path:Union['XAPath',str])->'AppleScript':
- """Loads an AppleScript (.scpt) file as a runnable AppleScript object.
+
[docs]defactivate(self)->'XAApplication':
+ """Activates the application, bringing its window(s) to the front and launching the application beforehand if necessary.
- :param path: The path of the .scpt file to load
- :type path: Union[XAPath, str]
- :return: The newly loaded AppleScript object
- :rtype: AppleScript
+ :return: A reference to the PyXA application object.
+ :rtype: XAApplication
- :Example 1: Load and run a script
+ .. seealso:: :func:`terminate`, :func:`unhide`, :func:`focus`
- >>> 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 '{ ... } ]>
- }
+ .. versionadded:: 0.0.1
+ """
+ self.xa_elem.activateWithOptions_(AppKit.NSApplicationActivateIgnoringOtherApps)
+ returnself
[docs]defsave(self,path:Union['XAPath',str,None]=None):
- """Saves the script to the specified file path, or to the path from which the script was loaded.
+
[docs]defquit(self)->'XAApplication':
+ """Quits the application. Synonymous with terminate().
- :param path: The path to save the script at, defaults to None
- :type path: Union[XAPath, str, None], optional
+ :return: A reference to the PyXA application object.
+ :rtype: XAApplication
- :Example 1: Save the script to a specified path
+ :Example: >>> 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
+ >>> safari = PyXA.Application("Safari")
+ >>> safari.quit()
- >>> 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()
+ .. seealso:: :func:`terminate`, :func:`activate`
- .. versionadded:: 0.0.9
+ .. versionadded:: 0.0.1 """
- ifpathisNoneandself.file_pathisNone:
- print("No path to save script to!")
- return
-
- ifisinstance(path,str):
- path=XAPath(path)
+ self.xa_elem.terminate()
+ returnself
[docs]defhide(self)->'XAApplication':
+ """Hides all windows of the application.
- ifpathisnotNone:
- self.__file_path=path
+ :return: A reference to the PyXA application object.
+ :rtype: XAApplication
- withopen(self.file_path.xa_elem.path(),"w")asf:
- f.write(source)
+ :Example:
-
[docs]defparse_result_data(result:dict)->List[Tuple[str,str]]:
- """Extracts string data from an AppleScript execution result dictionary.
+ >>> import PyXA
+ >>> safari = PyXA.Application("Safari")
+ >>> safari.hide()
- :param result: The execution result dictionary to extract data from
- :type result: dict
- :return: A list of responses contained in the result structured as tuples
- :rtype: List[Tuple[str, str]]
+ .. seealso:: :func:`unhide`
+
+ .. versionadded:: 0.0.1
+ """
+ self.xa_elem.hide()
+ returnself
+
+
[docs]defunhide(self)->'XAApplication':
+ """Unhides (reveals) all windows of the application, but does not does not activate them.
+
+ :return: A reference to the PyXA application object.
+ :rtype: XAApplication :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'), ...]
+ >>> safari = PyXA.Application("Safari")
+ >>> safari.unhide()
- .. versionadded:: 0.0.9
- """
- result=result["event"]
- response_objects=[]
- num_responses=result.numberOfItems()
- forresponse_indexinrange(1,num_responses+1):
- response=result.descriptorAtIndex_(response_index)
+ .. seealso:: :func:`hide`
- data=()
- num_params=response.numberOfItems()
- ifnum_params==0:
- data=response.stringValue().strip()
+ .. versionadded:: 0.0.1
+ """
+ self.xa_elem.unhide()
+ returnself
[docs]defunfocus(self)->'XAApplication':
+ """Unhides (reveals) the windows of all other applications, but does not activate them.
+ :return: A reference to the PyXA application object.
+ :rtype: XAApplication
+ :Example:
+ >>> import PyXA
+ >>> safari = PyXA.Application("Safari")
+ >>> safari.unfocus()
-
[docs]classXAClipboard(XAObject):
- """A wrapper class for managing and interacting with the system clipboard.
+ .. seealso:: :func:`focus`
- .. versionadded:: 0.0.5
- """
- def__init__(self):
- self.xa_elem=AppKit.NSPasteboard.generalPasteboard()
- self.content#: The content of the clipboard
+ .. versionadded:: 0.0.1
+ """
+ forappinself.xa_wksp.runningApplications():
+ app.unhide()
+ returnself
- :return: The list of strings currently copied to the clipboard
- :rtype: List[str]
+
[docs]defget_clipboard_representation(self)->list[Union[str,AppKit.NSURL,AppKit.NSImage]]:
+ """Gets a clipboard-codable representation of the application.
- .. versionadded:: 0.0.8
- """
- items=[]
- foriteminself.xa_elem.pasteboardItems():
- string=item.stringForType_(AppKit.NSPasteboardTypeString)
- ifstringisnotNone:
- items.append(string)
- returnitems
+ 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
-
[docs]defget_urls(self)->List['XAURL']:
- """Retrieves URL type data from the clipboard, as instances of :class:`XAURL` and :class:`XAPath`, if any such data exists.
+ 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 different for other applications.
- :return: The list of file URLs and web URLs currently copied to the clipboard
- :rtype: List[XAURL]
+ :return: The clipboard-codable representation
+ :rtype: list[Union[str, AppKit.NSURL, AppKit.NSImage]] .. versionadded:: 0.0.8 """
- items=[]
- foriteminself.xa_elem.pasteboardItems():
- url=None
- string=item.stringForType_(AppKit.NSPasteboardTypeURL)
- ifstringisNone:
- string=item.stringForType_(AppKit.NSPasteboardTypeFileURL)
- ifstringisnotNone:
- url=XAPath(XAURL(string).xa_elem)
- else:
- url=XAURL(string)
-
- ifurlisnotNone:
- items.append(url)
- returnitems
[docs]defget_images(self)->List['XAImage']:
- """Retrieves image type data from the clipboard, as instances of :class:`XAImage`, if any such data exists.
+
+
+
+######################
+### PyXA Utilities ###
+######################
+# SDEFParser, XAList, XAPredicate, XAURL, XAPath
+
[docs]classSDEFParser(XAObject):
+ def__init__(self,sdef_file:Union['XAPath',str]):
+ ifisinstance(sdef_file,str):
+ sdef_file=XAPath(sdef_file)
+ self.file=sdef_file#: The full path to the SDEF file to parse
+
+ self.app_name=""
+ self.scripting_suites=[]
+
+
[docs]classXAList(XAObject):
+ """A wrapper around NSArray and NSMutableArray objects enabling fast enumeration and lazy evaluation of Objective-C objects.
+
+ .. versionadded:: 0.0.3
+ """
+ def__init__(self,properties:dict,object_class:type=None,filter:Union[dict,None]=None):
+ """Creates an efficient wrapper object around a list of scriptable elements.
+
+ :param properties: PyXA properties passed to this object for utility purposes
+ :type properties: dict
+ :param object_class: _description_, defaults to None
+ :type object_class: type, optional
+ :param filter: A dictionary of properties and values to filter items by, defaults to None
+ :type filter: Union[dict, None], optional
+
+ .. versionchanged:: 0.0.8
+ The filter property is deprecated and will be removed in a future version. Use the :func:`filter` method instead.
+
+ .. versionadded:: 0.0.3
+ """
+ super().__init__(properties)
+ self.xa_ocls=object_class
+
+ ifnotisinstance(self.xa_elem,AppKit.NSArray):
+ self.xa_elem=AppKit.NSMutableArray.alloc().initWithArray_(self.xa_elem)
+
+ iffilterisnotNone:
+ self.xa_elem=XAPredicate().from_dict(filter).evaluate(self.xa_elem)
+
+
[docs]defby_property(self,property:str,value:Any)->XAObject:
+ """Retrieves the first element whose property value matches the given value, if one exists.
+
+ :param property: The property to match
+ :type property: str
+ :param value: The value to match
+ :type value: Any
+ :return: The matching element, if one is found
+ :rtype: 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>
+
+ .. versionadded:: 0.0.6
+ """
+ predicate=XAPredicate()
+ predicate.add_eq_condition(property,value)
+ ls=predicate.evaluate(self.xa_elem)
+ # if hasattr(ls, "get"):
+ # ls = predicate.evaluate(self.xa_elem).get()
+
+ iflen(ls)==0:
+ returnNone
+
+ obj=ls[0]
+ returnself._new_element(obj,self.xa_ocls)
+
+
[docs]defequalling(self,property:str,value:str)->XAObject:
+ """Retrieves all elements whose property value equals the given value.
+
+ :param property: The property to match
+ :type property: str
+ :param value: The value to search for
+ :type value: str
+ :return: The list of matching elements
+ :rtype: 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', ...]>
+
+ .. versionadded:: 0.1.0
+ """
+ predicate=XAPredicate()
+ predicate.add_eq_condition(property,value)
+ ls=predicate.evaluate(self.xa_elem)
+ returnself._new_element(ls,self.__class__)
+
+
[docs]defnot_equalling(self,property:str,value:str)->XAObject:
+ """Retrieves all elements whose property value does not equal the given value.
+
+ :param property: The property to match
+ :type property: str
+ :param value: The value to search for
+ :type value: str
+ :return: The list of matching elements
+ :rtype: 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', ...]>
+
+ .. versionadded:: 0.1.0
+ """
+ predicate=XAPredicate()
+ predicate.add_neq_condition(property,value)
+ ls=predicate.evaluate(self.xa_elem)
+ returnself._new_element(ls,self.__class__)
+
+
[docs]defcontaining(self,property:str,value:str)->XAObject:
+ """Retrieves all elements whose property value contains the given value.
+
+ :param property: The property to match
+ :type property: str
+ :param value: The value to search for
+ :type value: str
+ :return: The list of matching elements
+ :rtype: XAList
+
+ :Example:
+
+ >>> import PyXA
+ >>> app = PyXA.Application("Reminders")
+ >>> print(app.reminders().containing("name", "PyXA"))
+ <<class 'PyXA.apps.Reminders.XARemindersReminderList'>['PyXA v0.1.0 release']>
+
+ .. versionadded:: 0.0.6
+ """
+ predicate=XAPredicate()
+ predicate.add_contains_condition(property,value)
+ ls=predicate.evaluate(self.xa_elem)
+ returnself._new_element(ls,self.__class__)
+
+
[docs]defnot_containing(self,property:str,value:str)->XAObject:
+ """Retrieves all elements whose property value does not contain the given value.
+
+ :param property: The property to match
+ :type property: str
+ :param value: The value to search for
+ :type value: str
+ :return: The list of matching elements
+ :rtype: XAList
+
+ :Example:
+
+ >>> import PyXA
+ >>> app = PyXA.Application("Reminders")
+ >>> print(app.reminders().not_containing("name", " "))
+ <<class 'PyXA.apps.Reminders.XARemindersReminderList'>['Trash', 'Thing', 'Reminder', ...]>
+
+ .. versionadded:: 0.1.0
+ """
+ ls=XAPredicate.evaluate_with_format(self.xa_elem,f"NOT {property} CONTAINS \"{value}\"")
+ returnself._new_element(ls,self.__class__)
+
+
[docs]defbeginning_with(self,property:str,value:str)->XAObject:
+ """Retrieves all elements whose property value begins with the given value.
+
+ :param property: The property to match
+ :type property: str
+ :param value: The value to search for
+ :type value: str
+ :return: The list of matching elements
+ :rtype: 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', ...]>
+
+ .. versionadded:: 0.1.0
+ """
+ predicate=XAPredicate()
+ predicate.add_begins_with_condition(property,value)
+ ls=predicate.evaluate(self.xa_elem)
+ returnself._new_element(ls,self.__class__)
+
+
[docs]defending_with(self,property:str,value:str)->XAObject:
+ """Retrieves all elements whose property value ends with the given value.
+
+ :param property: The property to match
+ :type property: str
+ :param value: The value to search for
+ :type value: str
+ :return: The list of matching elements
+ :rtype: 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', ...]>
+
+ .. versionadded:: 0.1.0
+ """
+ predicate=XAPredicate()
+ predicate.add_ends_with_condition(property,value)
+ ls=predicate.evaluate(self.xa_elem)
+ returnself._new_element(ls,self.__class__)
+
+
[docs]defgreater_than(self,property:str,value:Union[int,float])->XAObject:
+ """Retrieves all elements whose property value is greater than the given value.
+
+ :param property: The property to match
+ :type property: str
+ :param value: The value to compare against
+ :type value: Union[int, float]
+ :return: The list of matching elements
+ :rtype: 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>
+
+ .. versionadded:: 0.1.0
+ """
+ predicate=XAPredicate()
+ predicate.add_gt_condition(property,value)
+ ls=predicate.evaluate(self.xa_elem)
+ returnself._new_element(ls,self.__class__)
+
+
[docs]defless_than(self,property:str,value:Union[int,float])->XAObject:
+ """Retrieves all elements whose property value is less than the given value.
+
+ :param property: The property to match
+ :type property: str
+ :param value: The value to compare against
+ :type value: Union[int, float]
+ :return: The list of matching elements
+ :rtype: 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']
+
+ .. versionadded:: 0.1.0
+ """
+ predicate=XAPredicate()
+ predicate.add_lt_condition(property,value)
+ ls=predicate.evaluate(self.xa_elem)
+ returnself._new_element(ls,self.__class__)
+
+
[docs]defbetween(self,property:str,value1:Union[int,float],value2:Union[int,float])->XAObject:
+ """Retrieves all elements whose property value is between the given values.
+
+ :param property: The property to match
+ :type property: str
+ :param value1: The lower-end of the range to match
+ :type value1: Union[int, float]
+ :param value2: The upper-end of the range to match
+ :type value2: Union[int, float]
+ :return: The list of matching elements
+ :rtype: 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']>
+
+ .. versionadded:: 0.1.0
+ """
+ predicate=XAPredicate()
+ predicate.add_gt_condition(property,value1)
+ predicate.add_lt_condition(property,value2)
+ ls=predicate.evaluate(self.xa_elem)
+ returnself._new_element(ls,self.__class__)
+
+
[docs]deffilter(self,filter:str,comparison_operation:Union[str,None]=None,value1:Union[Any,None]=None,value2:Union[Any,None]=None)->'XAList':
+ """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.
+
+ :param filter: A format string or a property name
+ :type filter: str
+ :param comparison_operation: The symbol or name of a comparison operation, such as > or <, defaults to None
+ :type comparison_operation: Union[str, None], optional
+ :param value1: The first value to compare each list item's property value against, defaults to None
+ :type value1: Union[Any, None], optional
+ :param value2: The second value to compare each list item's property value against, defaults to None
+ :type value2: Union[Any, None], optional
+ :return: The filter XAList object
+ :rtype: 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>
+
+ .. versionadded:: 0.0.8
+ """
+ ifcomparison_operationisnotNoneandvalue1isnotNone:
+ predicate=XAPredicate()
+ ifcomparison_operationin["=","==","eq","EQ","equals","EQUALS"]:
+ predicate.add_eq_condition(filter,value1)
+ elifcomparison_operationin["!=","!==","neq","NEQ","not equal to","NOT EQUAL TO"]:
+ predicate.add_neq_condition(filter,value1)
+ elifcomparison_operationin[">","gt","GT","greater than","GREATER THAN"]:
+ predicate.add_gt_condition(filter,value1)
+ elifcomparison_operationin["<","lt","LT","less than","LESS THAN"]:
+ predicate.add_lt_condition(filter,value1)
+ elifcomparison_operationin[">=","geq","GEQ","greater than or equal to","GREATER THAN OR EQUAL TO"]:
+ predicate.add_geq_condition(filter,value1)
+ elifcomparison_operationin["<=","leq","LEQ","less than or equal to","LESS THAN OR EQUAL TO"]:
+ predicate.add_leq_condition(filter,value1)
+ elifcomparison_operationin["begins with","beginswith","BEGINS WITH","BEGINSWITH"]:
+ predicate.add_begins_with_condition(filter,value1)
+ elifcomparison_operationin["contains","CONTAINS"]:
+ predicate.add_contains_condition(filter,value1)
+ elifcomparison_operationin["ends with","endswith","ENDS WITH","ENDSWITH"]:
+ predicate.add_ends_with_condition(filter,value1)
+ elifcomparison_operationin["between","BETWEEN"]:
+ predicate.add_between_condition(filter,value1,value2)
+ elifcomparison_operationin["matches","MATCHES"]:
+ predicate.add_match_condition(filter,value1)
+
+ filtered_list=predicate.evaluate(self.xa_elem)
+ returnsuper()._new_element(filtered_list,self.__class__)
+ else:
+ filtered_list=XAPredicate.evaluate_with_format(self.xa_elem,filter)
+ returnsuper()._new_element(filtered_list,self.__class__)
+
+
[docs]defat(self,index:int)->XAObject:
+ """Retrieves the element at the specified index.
+
+ :param index: The index of the desired element
+ :type index: int
+ :return: The PyXA-wrapped element object
+ :rtype: XAObject
+
+ .. versionadded:: 0.0.6
+ """
+ returnself._new_element(self.xa_elem[index],self.xa_ocls)
+
+ @property
+ deffirst(self)->XAObject:
+ """Retrieves the first element of the list as a wrapped PyXA object.
+
+ :return: The wrapped object
+ :rtype: XAObject
+
+ .. versionadded:: 0.0.3
+ """
+ returnself._new_element(self.xa_elem.firstObject(),self.xa_ocls)
+
+ @property
+ deflast(self)->XAObject:
+ """Retrieves the last element of the list as a wrapped PyXA object.
+
+ :return: The wrapped object
+ :rtype: XAObject
+
+ .. versionadded:: 0.0.3
+ """
+ returnself._new_element(self.xa_elem.lastObject(),self.xa_ocls)
+
+
[docs]defshuffle(self)->'XAList':
+ """Randomizes the order of objects in the list.
+
+ :return: A reference to the shuffled XAList
+ :rtype: XAList
+
+ .. versionadded:: 0.0.3
+ """
+ try:
+ self.xa_elem=self.xa_elem.shuffledArray()
+ exceptAttributeError:
+ random.shuffle(self.xa_elem)
+ returnself
+
+
[docs]defpush(self,*elements:list[XAObject])->Union[XAObject,list[XAObject],None]:
+ """Appends the object referenced by the provided PyXA wrapper to the end of the list.
+
+ .. versionadded:: 0.0.3
+ """
+ objects=[]
+ forelementinelements:
+ len_before=len(self.xa_elem)
+ self.xa_elem.addObject_(element.xa_elem)
+
+ iflen(self.xa_elem)==len_before:
+ # Object wasn't added -- try force-getting the list before adding
+ self.xa_elem.get().addObject_(element.xa_elem)
+
+ iflen(self.xa_elem)>len_before:
+ objects.append(self[len(self.xa_elem)-1])
+
+ iflen(objects)==1:
+ returnobjects[0]
+
+ iflen(objects)==0:
+ returnNone
+
+ returnobjects
+
+
[docs]definsert(self,element:XAObject,index:int):
+ """Inserts the object referenced by the provided PyXA wrapper at the specified index.
+
+ .. versionadded:: 0.0.3
+ """
+ self.xa_elem.insertObject_atIndex_(element.xa_elem,index)
+
+
[docs]defpop(self,index:int=-1)->XAObject:
+ """Removes the object at the specified index from the list and returns it.
+
+ .. versionadded:: 0.0.3
+ """
+ removed=self.xa_elem.lastObject()
+ self.xa_elem.removeLastObject()
+ returnself._new_element(removed,self.xa_ocls)
[docs]deffrom_dict(self,ref_dict:dict)->'XAPredicate':
+ """Populates the XAPredicate object from the supplied dictionary.
+
+ The predicate will use == for all comparisons.
+
+ :param ref_dict: A specification of key, value pairs
+ :type ref_dict: dict
+ :return: The populated predicate object
+ :rtype: XAPredicate
+
+ .. versionadded:: 0.0.4
+ """
+ forkey,valueinref_dict.items():
+ self.keys.append(key)
+ self.operators.append("==")
+ self.values.append(value)
+ returnself
+
+
[docs]deffrom_args(self,*args)->'XAPredicate':
+ """Populates the XAPredicate object from the supplied key, value argument pairs.
+
+ The number of keys and values must be equal. The predicate will use == for all comparisons.
+
+ :raises InvalidPredicateError: Raised when the number of keys does not match the number of values
+ :return: The populated predicate object
+ :rtype: XAPredicate
+
+ .. versionadded:: 0.0.4
+ """
+ arg_num=len(args)
+ ifarg_num%2!=0:
+ raiseInvalidPredicateError("The number of keys and values must be equal; the number of arguments must be an even number.")
+
+ forindex,valueinenumerate(args):
+ ifindex%2==0:
+ self.keys.append(value)
+ self.operators.append("==")
+ self.values.append(args[index+1])
+ returnself
+
+
[docs]defevaluate(self,target:Union[AppKit.NSArray,XAList])->AppKit.NSArray:
+ """Evaluates the predicate on the given array.
+
+ :param target: The array to evaluate against the predicate
+ :type target: AppKit.NSArray
+ :return: The filtered array
+ :rtype: AppKit.NSArray
+
+ .. versionadded:: 0.0.4
+ """
+ target_list=target
+ ifisinstance(target,XAList):
+ target_list=target.xa_elem
+
+ placeholders=["%@"]*len(self.values)
+ expressions=[" ".join(expr)forexprinzip(self.keys,self.operators,placeholders)]
+ format="( "+" ) && ( ".join(expressions)+" )"
+
+ predicate=AppKit.NSPredicate.predicateWithFormat_(format,*self.values)
+ ls=target_list.filteredArrayUsingPredicate_(predicate)
+
+ iflen(ls)==0:
+ try:
+ # Not sure why this is necessary sometimes, but it is.
+ predicate=str(predicate)
+ ls=target_list.filteredArrayUsingPredicate_(AppKit.NSPredicate.predicateWithFormat_(predicate))
+ exceptValueError:
+ pass
+
+ ifisinstance(target,XAList):
+ returntarget.__class__({
+ "parent":target,
+ "appspace":self.xa_apsp,
+ "workspace":self.xa_wksp,
+ "element":ls,
+ "appref":self.xa_aref,
+ })
+ returnls
+
+
[docs]defevaluate_with_format(target:Union[AppKit.NSArray,XAList],fmt:str)->AppKit.NSArray:
+ """Evaluates the specified array against a predicate with the given format.
+
+ :param target: The array to filter
+ :type target: AppKit.NSArray
+ :param fmt: The format string for the predicate
+ :type fmt: str
+ :return: The filtered array
+ :rtype: AppKit.NSArray
+
+ .. versionadded:: 0.0.4
+ """
+ target_list=target
+ ifisinstance(target,XAList):
+ target_list=target.xa_elem
+
+ predicate=AppKit.NSPredicate.predicateWithFormat_(fmt)
+ ls=target_list.filteredArrayUsingPredicate_(predicate)
+
+ ifisinstance(target,XAList):
+ returntarget.__class__({
+ "parent":target,
+ "appspace":AppKit.NSApplication.sharedApplication(),
+ "workspace":AppKit.NSWorkspace.sharedWorkspace(),
+ "element":ls,
+ "appref":AppKit.NSApplication.sharedApplication(),
+ })
+ returnls
+
+
[docs]defevaluate_with_dict(target:Union[AppKit.NSArray,XAList],properties_dict:dict)->AppKit.NSArray:
+ """Evaluates the specified array against a predicate constructed from the supplied dictionary.
+
+ The predicate will use == for all comparisons.
+
+ :param target: The array to filter
+ :type target: AppKit.NSArray
+ :param properties_dict: The specification of key, value pairs
+ :type properties_dict: dict
+ :return: The filtered array
+ :rtype: AppKit.NSArray
+
+ .. versionadded:: 0.0.4
+ """
+ target_list=target
+ ifisinstance(target,XAList):
+ target_list=target.xa_elem
+
+ fmt=""
+ forkey,valueinproperties_dict.items():
+ ifisinstance(value,str):
+ value="'"+value+"'"
+ fmt+=f"( {key} == {value} ) &&"
+
+ predicate=AppKit.NSPredicate.predicateWithFormat_(fmt[:-3])
+ ls=target_list.filteredArrayUsingPredicate_(predicate)
+
+ ifisinstance(target,XAList):
+ returntarget.__class__({
+ "parent":target,
+ "appspace":AppKit.NSApplication.sharedApplication(),
+ "workspace":AppKit.NSWorkspace.sharedWorkspace(),
+ "element":ls,
+ "appref":AppKit.NSApplication.sharedApplication(),
+ })
+ returnls
+
+ # EQUAL
+
[docs]defadd_eq_condition(self,property:str,value:Any):
+ """Appends an `==` condition to the end of the predicate format.
+
+ The added condition will have the form `property == value`.
+
+ :param property: A property of an object to check the condition against
+ :type property: str
+ :param value: The target value of the condition
+ :type value: Any
+
+ .. versionadded:: 0.0.4
+ """
+ self.keys.append(property)
+ self.operators.append("==")
+ self.values.append(value)
+
+
[docs]definsert_eq_condition(self,index:int,property:str,value:Any):
+ """Inserts an `==` condition to the predicate format at the desired location, specified by index.
+
+ The added condition will have the form `property == value`.
+
+ :param property: A property of an object to check the condition against
+ :type property: str
+ :param value: The target value of the condition
+ :type value: Any
+
+ .. versionadded:: 0.0.4
+ """
+ self.keys.insert(index,property)
+ self.operators.insert(index,"==")
+ self.values.insert(index,value)
+
+ # NOT EQUAL
+
[docs]defadd_neq_condition(self,property:str,value:Any):
+ """Appends a `!=` condition to the end of the predicate format.
+
+ The added condition will have the form `property != value`.
+
+ :param property: A property of an object to check the condition against
+ :type property: str
+ :param value: The target value of the condition
+ :type value: Any
+
+ .. versionadded:: 0.0.4
+ """
+ self.keys.append(property)
+ self.operators.append("!=")
+ self.values.append(value)
+
+
[docs]definsert_neq_condition(self,index:int,property:str,value:Any):
+ """Inserts a `!=` condition to the predicate format at the desired location, specified by index.
+
+ The added condition will have the form `property != value`.
+
+ :param property: A property of an object to check the condition against
+ :type property: str
+ :param value: The target value of the condition
+ :type value: Any
+
+ .. versionadded:: 0.0.4
+ """
+ self.keys.insert(index,property)
+ self.operators.insert(index,"!=")
+ self.values.insert(index,value)
+
+ # GREATER THAN OR EQUAL
+
[docs]defadd_geq_condition(self,property:str,value:Any):
+ """Appends a `>=` condition to the end of the predicate format.
+
+ The added condition will have the form `property >= value`.
+
+ :param property: A property of an object to check the condition against
+ :type property: str
+ :param value: The target value of the condition
+ :type value: Any
+
+ .. versionadded:: 0.0.4
+ """
+ self.keys.append(property)
+ self.operators.append(">=")
+ self.values.append(value)
+
+
[docs]definsert_geq_condition(self,index:int,property:str,value:Any):
+ """Inserts a `>=` condition to the predicate format at the desired location, specified by index.
+
+ The added condition will have the form `property >= value`.
+
+ :param property: A property of an object to check the condition against
+ :type property: str
+ :param value: The target value of the condition
+ :type value: Any
+
+ .. versionadded:: 0.0.4
+ """
+ self.keys.insert(index,property)
+ self.operators.insert(index,">=")
+ self.values.insert(index,value)
+
+ # LESS THAN OR EQUAL
+
[docs]defadd_leq_condition(self,property:str,value:Any):
+ """Appends a `<=` condition to the end of the predicate format.
+
+ The added condition will have the form `property <= value`.
+
+ :param property: A property of an object to check the condition against
+ :type property: str
+ :param value: The target value of the condition
+ :type value: Any
+
+ .. versionadded:: 0.0.4
+ """
+ self.keys.append(property)
+ self.operators.append("<=")
+ self.values.append(value)
+
+
[docs]definsert_leq_condition(self,index:int,property:str,value:Any):
+ """Inserts a `<=` condition to the predicate format at the desired location, specified by index.
+
+ The added condition will have the form `property <= value`.
+
+ :param property: A property of an object to check the condition against
+ :type property: str
+ :param value: The target value of the condition
+ :type value: Any
+
+ .. versionadded:: 0.0.4
+ """
+ self.keys.insert(index,property)
+ self.operators.insert(index,"<=")
+ self.values.insert(index,value)
+
+ # GREATER THAN
+
[docs]defadd_gt_condition(self,property:str,value:Any):
+ """Appends a `>` condition to the end of the predicate format.
+
+ The added condition will have the form `property > value`.
+
+ :param property: A property of an object to check the condition against
+ :type property: str
+ :param value: The target value of the condition
+ :type value: Any
+
+ .. versionadded:: 0.0.4
+ """
+ self.keys.append(property)
+ self.operators.append(">")
+ self.values.append(value)
+
+
[docs]definsert_gt_condition(self,index:int,property:str,value:Any):
+ """Inserts a `>` condition to the predicate format at the desired location, specified by index.
+
+ The added condition will have the form `property > value`.
+
+ :param property: A property of an object to check the condition against
+ :type property: str
+ :param value: The target value of the condition
+ :type value: Any
+
+ .. versionadded:: 0.0.4
+ """
+ self.keys.insert(index,property)
+ self.operators.insert(index,">")
+ self.values.insert(index,value)
+
+ # LESS THAN
+
[docs]defadd_lt_condition(self,property:str,value:Any):
+ """Appends a `<` condition to the end of the predicate format.
+
+ The added condition will have the form `property < value`.
+
+ :param property: A property of an object to check the condition against
+ :type property: str
+ :param value: The target value of the condition
+ :type value: Any
+
+ .. versionadded:: 0.0.4
+ """
+ self.keys.append(property)
+ self.operators.append("<")
+ self.values.append(value)
+
+
[docs]definsert_lt_condition(self,index:int,property:str,value:Any):
+ """Inserts a `<` condition to the predicate format at the desired location, specified by index.
+
+ The added condition will have the form `property < value`.
+
+ :param property: A property of an object to check the condition against
+ :type property: str
+ :param value: The target value of the condition
+ :type value: Any
+
+ .. versionadded:: 0.0.4
+ """
+ self.keys.insert(index,property)
+ self.operators.insert(index,"<")
+ self.values.insert(index,value)
+
+ # BETWEEN
+
[docs]defadd_between_condition(self,property:str,value1:Union[int,float],value2:Union[int,float]):
+ """Appends a `BETWEEN` condition to the end of the predicate format.
+
+ The added condition will have the form `property BETWEEN [value1, value2]`.
+
+ :param property: A property of an object to check the condition against
+ :type property: str
+ :param value1: The lower target value of the condition
+ :type value1: Union[int, float]
+ :param value2: The upper target value of the condition
+ :type value2: Union[int, float]
+
+ .. versionadded:: 0.0.4
+ """
+ self.keys.append(property)
+ self.operators.append("BETWEEN")
+ self.values.append([value1,value2])
+
+
[docs]definsert_between_condition(self,index:int,property:str,value1:Union[int,float],value2:Union[int,float]):
+ """Inserts a `BETWEEN` condition to the predicate format at the desired location, specified by index.
+
+ The added condition will have the form `property BETWEEN [value1, value2]`.
+
+ :param property: A property of an object to check the condition against
+ :type property: str
+ :param value1: The lower target value of the condition
+ :type value1: Union[int, float]
+ :param value2: The upper target value of the condition
+ :type valu2e: Union[int, float]
+
+ .. versionadded:: 0.0.4
+ """
+ self.keys.insert(index,property)
+ self.operators.insert(index,"BETWEEN")
+ self.values.insert(index,[value1,value2])
+
+ # BEGINSWITH
+
[docs]defadd_begins_with_condition(self,property:str,value:Any):
+ """Appends a `BEGINSWITH` condition to the end of the predicate format.
+
+ The added condition will have the form `property BEGINSWITH value`.
+
+ :param property: A property of an object to check the condition against
+ :type property: str
+ :param value: The target value of the condition
+ :type value: Any
+
+ .. versionadded:: 0.0.4
+ """
+ self.keys.append(property)
+ self.operators.append("BEGINSWITH")
+ self.values.append(value)
+
+
[docs]definsert_begins_with_condition(self,index:int,property:str,value:Any):
+ """Inserts a `BEGINSWITH` condition to the predicate format at the desired location, specified by index.
+
+ The added condition will have the form `property BEGINSWITH value`.
+
+ :param property: A property of an object to check the condition against
+ :type property: str
+ :param value: The target value of the condition
+ :type value: Any
+
+ .. versionadded:: 0.0.4
+ """
+ self.keys.insert(index,property)
+ self.operators.insert(index,"BEGINSWITH")
+ self.values.insert(index,value)
+
+ # ENDSWITH
+
[docs]defadd_ends_with_condition(self,property:str,value:Any):
+ """Appends a `ENDSWITH` condition to the end of the predicate format.
+
+ The added condition will have the form `property ENDSWITH value`.
+
+ :param property: A property of an object to check the condition against
+ :type property: str
+ :param value: The target value of the condition
+ :type value: Any
+
+ .. versionadded:: 0.0.4
+ """
+ self.keys.append(property)
+ self.operators.append("ENDSWITH")
+ self.values.append(value)
+
+
[docs]definsert_ends_with_condition(self,index:int,property:str,value:Any):
+ """Inserts a `ENDSWITH` condition to the predicate format at the desired location, specified by index.
+
+ The added condition will have the form `property ENDSWITH value`.
+
+ :param property: A property of an object to check the condition against
+ :type property: str
+ :param value: The target value of the condition
+ :type value: Any
+
+ .. versionadded:: 0.0.4
+ """
+ self.keys.insert(index,property)
+ self.operators.insert(index,"ENDSWITH")
+ self.values.insert(index,value)
+
+ # CONTAINS
+
[docs]defadd_contains_condition(self,property:str,value:Any):
+ """Appends a `CONTAINS` condition to the end of the predicate format.
+
+ The added condition will have the form `property CONTAINS value`.
+
+ :param property: A property of an object to check the condition against
+ :type property: str
+ :param value: The target value of the condition
+ :type value: Any
+
+ .. versionadded:: 0.0.4
+ """
+ self.keys.append(property)
+ self.operators.append("CONTAINS")
+ self.values.append(value)
+
+
[docs]definsert_contains_condition(self,index:int,property:str,value:Any):
+ """Inserts a `CONTAINS` condition to the predicate format at the desired location, specified by index.
+
+ The added condition will have the form `property CONTAINS value`.
+
+ :param property: A property of an object to check the condition against
+ :type property: str
+ :param value: The target value of the condition
+ :type value: Any
+
+ .. versionadded:: 0.0.4
+ """
+ self.keys.insert(index,property)
+ self.operators.insert(index,"CONTAINS")
+ self.values.insert(index,value)
+
+ # MATCHES
+
[docs]defadd_match_condition(self,property:str,value:Any):
+ """Appends a `MATCHES` condition to the end of the predicate format.
+
+ The added condition will have the form `property MATCHES value`.
+
+ :param property: A property of an object to check the condition against
+ :type property: str
+ :param value: The target value of the condition
+ :type value: Any
+
+ .. versionadded:: 0.0.4
+ """
+ self.keys.append(property)
+ self.operators.append("MATCHES")
+ self.values.append(value)
+
+
[docs]definsert_match_condition(self,index:int,property:str,value:Any):
+ """Inserts a `MATCHES` condition to the predicate format at the desired location, specified by index.
+
+ The added condition will have the form `property MATCHES value`.
+
+ :param property: A property of an object to check the condition against
+ :type property: str
+ :param value: The target value of the condition
+ :type value: Any
+
+ .. versionadded:: 0.0.4
+ """
+ self.keys.insert(index,property)
+ self.operators.insert(index,"MATCHES")
+ self.values.insert(index,value)
+
+
[docs]defget_clipboard_representation(self)->str:
+ """Gets a clipboard-codable representation of the predicate.
+
+ When a predicate is copied to the clipboard, the string representation of the predicate is added to the clipboard.
+
+ :return: The string representation of the predicate
+ :rtype: str
+
+ .. versionadded:: 0.0.8
+ """
+ placeholders=["%@"]*len(self.values)
+ expressions=[" ".join(expr)forexprinzip(self.keys,self.operators,placeholders)]
+ format="( "+" ) && ( ".join(expressions)+" )"
+ predicate=AppKit.NSPredicate.predicateWithFormat_(format,*self.values)
+ returnpredicate.predicateFormat()
+
+
+
+
+
[docs]classXAURL(XAObject,XAClipboardCodable):
+ """A URL using any scheme recognized by the system. This can be a file URL.
+
+ .. versionadded:: 0.0.5
+ """
+ def__init__(self,url:Union[str,AppKit.NSURL,'XAURL','XAPath']):
+ super().__init__()
+ self.parameters:str#: The query parameters of the URL
+ self.scheme:str#: The URI scheme of the URL
+ self.fragment:str#: The fragment identifier following a # symbol in the URL
+ self.port:int#: The port that the URL points to
+ self.html:element.tag#: The html of the URL
+ self.title:str#: The title of the URL
+ self.soup:BeautifulSoup=None#: The bs4 object for the URL, starts as None until a bs4-related action is made
+ self.url:str#: The string form of the URL
+
+ ifisinstance(url,str):
+ logging.debug("Initializing XAURL from string")
+ # URL-encode spaces
+ url=url.replace(" ","%20")
+
+ ifurl.startswith("/"):
+ # Prepend file scheme
+ url="file://"+url
+ elifurl.replace(".","").isdecimal():
+ # URL is an IP -- must add http:// prefix
+ if":"notinurl:
+ # No port provided, add port 80 by default
+ url="http://"+url+":80"
+ else:
+ url="http://"+url
+ elif"://"notinurl:
+ # URL is not currently valid, try prepending http://
+ url="http://"+url
+
+ self.url=url
+ url=AppKit.NSURL.alloc().initWithString_(url)
+ elifisinstance(url,XAURL)orisinstance(url,XAPath):
+ logging.debug("Initializing XAURL from XAURL/XAPath")
+ self.url=url.url
+ url=url.xa_elem
+
+ self.xa_elem=url
+
+ @property
+ defbase_url(self)->str:
+ returnself.xa_elem.host()
+
+ @property
+ defparameters(self)->str:
+ returnself.xa_elem.query()
+
+ @property
+ defscheme(self)->str:
+ returnself.xa_elem.scheme()
+
+ @property
+ deffragment(self)->str:
+ returnself.xa_elem.fragment()
+
+ @property
+ defhtml(self)->element.Tag:
+ ifself.soupisNone:
+ self.__get_soup()
+ returnself.soup.html
+
+ @property
+ deftitle(self)->str:
+ ifself.soupisNone:
+ self.__get_soup()
+ returnself.soup.title.text
+
+ def__get_soup(self):
+ req=requests.get(str(self.xa_elem))
+ self.soup=BeautifulSoup(req.text,"html.parser")
+
+
[docs]defopen(self):
+ """Opens the URL in the appropriate default application.
+
+ .. versionadded:: 0.0.5
+ """
+ AppKit.NSWorkspace.sharedWorkspace().openURL_(self.xa_elem)
+
+
[docs]defextract_text(self)->list[str]:
+ """Extracts the visible text from the webpage that the URL points to.
+
+ :return: The list of extracted lines of text
+ :rtype: list[str]
+
+ .. versionadded:: 0.0.8
+ """
+ ifself.soupisNone:
+ self.__get_soup()
+ returnself.soup.get_text().splitlines()
+
+
[docs]defextract_images(self)->list['XAImage']:
+ """Extracts all images from HTML of the webpage that the URL points to.
+
+ :return: The list of extracted images
+ :rtype: list[XAImage]
+
+ .. versionadded:: 0.0.8
+ """
+ data=AppKit.NSData.alloc().initWithContentsOfURL_(AppKit.NSURL.URLWithString_(str(self.xa_elem)))
+ image=AppKit.NSImage.alloc().initWithData_(data)
+
+ ifimageisnotNone:
+ image_object=XAImage(image,name=self.xa_elem.pathComponents()[-1])
+ return[image_object]
+ else:
+ ifself.soupisNone:
+ self.__get_soup()
+
+ images=self.soup.findAll("img")
+ image_objects=[]
+ forimageinimages:
+ image_src=image["src"]
+ ifimage_src.startswith("/"):
+ image_src=str(self)+str(image["src"])
+
+ data=AppKit.NSData.alloc().initWithContentsOfURL_(AppKit.NSURL.URLWithString_(image_src))
+ image=AppKit.NSImage.alloc().initWithData_(data)
+ ifimageisnotNone:
+ image_object=XAImage(image,name=XAURL(image_src).xa_elem.pathComponents()[-1])
+ image_objects.append(image_object)
+
+ returnimage_objects
+
+
[docs]defget_clipboard_representation(self)->list[Union[AppKit.NSURL,str]]:
+ """Gets a clipboard-codable representation of the URL.
+
+ When the clipboard content is set to a URL, the raw URL data and the string representation of the URL are added to the clipboard.
+
+ :return: The clipboard-codable form of the URL
+ :rtype: Any
+
+ .. versionadded:: 0.0.8
+ """
+ return[self.xa_elem,str(self.xa_elem)]
[docs]classXAPath(XAObject,XAClipboardCodable):
+ """A path to a file on the disk.
+
+ .. versionadded:: 0.0.5
+ """
+ def__init__(self,path:Union[str,AppKit.NSURL]):
+ super().__init__()
+ ifisinstance(path,str):
+ path=AppKit.NSURL.alloc().initFileURLWithPath_(path)
+ self.xa_elem=path
+ self.path=path.path()#: The path string without the file:// prefix
+ self.url=str(self.xa_elem)#: The path string with the file:// prefix included
+ self.xa_wksp=AppKit.NSWorkspace.sharedWorkspace()
+
+
[docs]defopen(self):
+ """Opens the file in its default application.
+
+ .. versionadded: 0.0.5
+ """
+ self.xa_wksp.openURL_(self.xa_elem)
+
+
[docs]defshow_in_finder(self):
+ """Opens a Finder window showing the folder containing this path, with the associated file selected. Synonymous with :func:`select`.
+
+ .. versionadded: 0.0.9
+ """
+ self.select()
+
+
[docs]defselect(self):
+ """Opens a Finder window showing the folder containing this path, with the associated file selected. Synonymous with :func:`show_in_finder`.
+
+ .. versionadded: 0.0.5
+ """
+ self.xa_wksp.activateFileViewerSelectingURLs_([self.xa_elem])
+
+
[docs]defget_clipboard_representation(self)->list[Union[AppKit.NSURL,str]]:
+ """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.
+
+ :return: The clipboard-codable form of the path
+ :rtype: Any
+
+ .. versionadded:: 0.0.8
+ """
+ return[self.xa_elem,self.xa_elem.path()]
[docs]classAppleScript(XAObject):
+ """A class for constructing and executing AppleScript scripts.
+
+ .. versionadded:: 0.0.5
+ """
+ def__init__(self,script:Union[str,list[str],None]=None):
+ """Creates a new AppleScript object.
+
+ :param script: A string or list of strings representing lines of AppleScript code, or the path to a script plaintext file, defaults to None
+ :type script: Union[str, list[str], None], optional
+
+ .. versionadded:: 0.0.5
+ """
+ self.script:list[str]#: The lines of AppleScript code contained in the script
+ self.last_result:Any#: The return value of the last execution of the script
+ self.file_path:XAPath#: The file path of this script, if one exists
+
+ ifisinstance(script,str):
+ ifscript.startswith("/"):
+ withopen(script,'r')asf:
+ script=f.readlines()
+ else:
+ self.script=[script]
+ elifisinstance(script,list):
+ self.script=script
+ elifscript==None:
+ self.script=[]
+
+ @property
+ deflast_result(self)->Any:
+ returnself.__last_result
+
+ @property
+ deffile_path(self)->'XAPath':
+ returnself.__file_path
+
+
[docs]defadd(self,script:Union[str,list[str],'AppleScript']):
+ """Adds the supplied string, list of strings, or script as a new line entry in the script.
+
+ :param script: The script to append to the current script string.
+ :type script: Union[str, list[str], AppleScript]
+
+ :Example:
+
+ >>> import PyXA
+ >>> script = PyXA.AppleScript("tell application \"Safari\"")
+ >>> script.add("print the document of window 1")
+ >>> script.add("end tell")
+ >>> script.run()
+
+ .. versionadded:: 0.0.5
+ """
+ ifisinstance(script,str):
+ self.script.append(script)
+ elifisinstance(script,list):
+ self.script.extend(script)
+ elifisinstance(script,AppleScript):
+ self.script.extend(script.script)
+
+
[docs]definsert(self,index:int,script:Union[str,list[str],'AppleScript']):
+ """Inserts the supplied string, list of strings, or script as a line entry in the script starting at the given line index.
+
+ :param index: The line index to begin insertion at
+ :type index: int
+ :param script: The script to insert into the current script
+ :type script: Union[str, list[str], AppleScript]
+
+ :Example:
+
+ >>> import PyXA
+ >>> script = PyXA.AppleScript.load("/Users/exampleUser/Downloads/Test.scpt")
+ >>> script.insert(1, "activate")
+ >>> script.run()
+
+ .. versionadded:: 0.0.9
+ """
+ ifisinstance(script,str):
+ self.script.insert(index,script)
+ elifisinstance(script,list):
+ forlineinscript:
+ self.script.insert(index,line)
+ index+=1
+ elifisinstance(script,AppleScript):
+ forlineinscript.script:
+ self.script.insert(index,line)
+ index+=1
+
+
[docs]defpop(self,index:int=-1)->str:
+ """Removes the line at the given index from the script.
+
+ :param index: The index of the line to remove
+ :type index: int
+ :return: The text of the removed line
+ :rtype: str
+
+ :Example:
+
+ >>> import PyXA
+ >>> script = PyXA.AppleScript.load("/Users/exampleUser/Downloads/Test.scpt")
+ >>> print(script.pop(1))
+ get chats
+
+ .. versionadded:: 0.0.9
+ """
+ returnself.script.pop(index)
[docs]classXAClipboard(XAObject):
+ """A wrapper class for managing and interacting with the system clipboard.
+
+ .. versionadded:: 0.0.5
+ """
+ def__init__(self):
+ self.xa_elem=AppKit.NSPasteboard.generalPasteboard()
+ self.content#: The content of the clipboard
+
+ @property
+ defcontent(self)->dict[str,list[Any]]:
+ info_by_type={}
+ foriteminself.xa_elem.pasteboardItems():
+ foritem_typeinitem.types():
+ info_by_type[item_type]={
+ "data":item.dataForType_(item_type),
+ "properties":item.propertyListForType_(item_type),
+ "strings":item.stringForType_(item_type),
+ }
+ returninfo_by_type
+
+ @content.setter
+ defcontent(self,value:list[Any]):
+ ifnotisinstance(value,list):
+ value=[value]
+ self.xa_elem.clearContents()
+ forindex,iteminenumerate(value):
+ ifitem==None:
+ value[index]=""
+ elifisinstance(item,XAObject):
+ ifnotisinstance(item,XAClipboardCodable):
+ print(item,"is not a clipboard-codable object.")
+ continue
+ ifisinstance(item.xa_elem,ScriptingBridge.SBElementArray)anditem.xa_elem.get()isNone:
+ value[index]=""
+ else:
+ content=item.get_clipboard_representation()
+ ifisinstance(content,list):
+ value.pop(index)
+ value+=content
+ else:
+ value[index]=content
+ elifisinstance(item,int)orisinstance(item,float):
+ value[index]=str(item)
+ self.xa_elem.writeObjects_(value)
+
+
[docs]defclear(self):
+ """Clears the system clipboard.
+
+ .. versionadded:: 0.0.5
+ """
+ self.xa_elem.clearContents()
+
+
[docs]defget_strings(self)->list[str]:
+ """Retrieves string type data from the clipboard, if any such data exists.
+
+ :return: The list of strings currently copied to the clipboard
+ :rtype: list[str]
+
+ .. versionadded:: 0.0.8
+ """
+ items=[]
+ foriteminself.xa_elem.pasteboardItems():
+ string=item.stringForType_(AppKit.NSPasteboardTypeString)
+ ifstringisnotNone:
+ items.append(string)
+ returnitems
+
+
[docs]defget_urls(self)->list['XAURL']:
+ """Retrieves URL type data from the clipboard, as instances of :class:`XAURL` and :class:`XAPath`, if any such data exists.
+
+ :return: The list of file URLs and web URLs currently copied to the clipboard
+ :rtype: list[XAURL]
+
+ .. versionadded:: 0.0.8
+ """
+ items=[]
+ foriteminself.xa_elem.pasteboardItems():
+ url=None
+ string=item.stringForType_(AppKit.NSPasteboardTypeURL)
+ ifstringisNone:
+ string=item.stringForType_(AppKit.NSPasteboardTypeFileURL)
+ ifstringisnotNone:
+ url=XAPath(XAURL(string).xa_elem)
+ else:
+ url=XAURL(string)
+
+ ifurlisnotNone:
+ items.append(url)
+ returnitems
+
+
[docs]defget_images(self)->list['XAImage']:
+ """Retrieves image type data from the clipboard, as instances of :class:`XAImage`, if any such data exists. :return: The list of images currently copied to the clipboard
- :rtype: List[XAImage]
+ :rtype: list[XAImage]
+
+ .. versionadded:: 0.0.8
+ """
+ image_types=[AppKit.NSPasteboardTypePNG,AppKit.NSPasteboardTypeTIFF,'public.jpeg','com.apple.icns']
+ items=[]
+ foriteminself.xa_elem.pasteboardItems():
+ forimage_typeinimage_types:
+ ifimage_typeinitem.types():
+ img=XAImage(data=item.dataForType_(image_type))
+ items.append(img)
+ returnitems
+
+
[docs]defset_contents(self,content:list[Any]):
+ """Sets the content of the clipboard
+
+ :param content: A list of the content to add fill the clipboard with.
+ :type content: list[Any]
+
+ .. deprecated:: 0.0.8
+ Set the :ivar:`content` property directly instead.
+
+ .. versionadded:: 0.0.5
+ """
+ self.xa_elem.clearContents()
+ self.xa_elem.writeObjects_(content)
+
+
+
+
+
[docs]classXANotification(XAObject):
+ """A class for managing and interacting with notifications.
+
+ .. versionadded:: 0.0.9
+ """
+ def__init__(self,text:str,title:Union[str,None]=None,subtitle:Union[str,None]=None,sound_name:Union[str,None]=None):
+ """Initializes a notification object.
+
+ :param text: The main text of the notification
+ :type text: str
+ :param title: The title of the notification, defaults to None
+ :type title: Union[str, None], optional
+ :param subtitle: The subtitle of the notification, defaults to None
+ :type subtitle: Union[str, None], optional
+ :param sound_name: The sound to play when the notification is displayed, defaults to None
+ :type sound_name: Union[str, None], optional
+
+ .. versionadded:: 0.0.9
+ """
+ self.text=text
+ self.title=title
+ self.subtitle=subtitle
+ self.sound_name=sound_name
+
+
[docs]defdisplay(self):
+ """Displays the notification.
+
+ .. todo::
+
+ Currently uses :func:`subprocess.Popen`. Should use UserNotifications in the future.
+
+ .. versionadded:: 0.0.9
+ """
+ script=AppleScript()
+ script.add(f"display notification \\\"{self.text}\\\"")
+
+ ifself.titleisnotNone:
+ script.add(f"with title \\\"{self.title}\\\"")
+
+ ifself.subtitleisnotNone:
+ script.add(f"subtitle \\\"{self.subtitle}\\\"")
+
+ ifself.sound_nameisnotNone:
+ script.add(f"sound name \\\"{self.sound_name}\\\"")
+
+ cmd="osascript -e \""+" ".join(script.script)+"\""
+ subprocess.Popen([cmd],shell=True)
+
+
+
+
+
[docs]classXAProcess(XAObject):
+ def__init__(self,properties):
+ super().__init__(properties)
+ self.xa_wcls=properties["window_class"]
+
+ self.front_window:XAWindow#: The front window of the application process
+
+ @property
+ deffront_window(self)->'XAWindow':
+ returnself._new_element(self.xa_elem.windows()[0],XAWindow)
+
+
[docs]classXACommandDetector(XAObject):
+ """A command-based query detector.
+
+ .. versionadded:: 0.0.9
+ """
+ def__init__(self,command_function_map:Union[dict[str,Callable[[],Any]],None]=None):
+ """Creates a command detector object.
+
+ :param command_function_map: A dictionary mapping command strings to function objects
+ :type command_function_map: dict[str, Callable[[], Any]]
+
+ .. versionadded:: 0.0.9
+ """
+ self.command_function_map=command_function_mapor{}#: The dictionary of commands and corresponding functions to run upon detection
+
+
[docs]defon_detect(self,command:str,function:Callable[[],Any]):
+ """Adds or replaces a command to listen for upon calling :func:`listen`, and associates the given function with that command.
+
+ :param command: The command to listen for
+ :type command: str
+ :param function: The function to call when the command is heard
+ :type function: Callable[[], Any]
+
+ :Example:
+
+ >>> detector = PyXA.XACommandDetector()
+ >>> detector.on_detect("go to google", PyXA.XAURL("http://google.com").open)
+ >>> detector.listen()
+
+ .. versionadded:: 0.0.9
+ """
+ self.command_function_map[command]=function
[docs]classXASpeechRecognizer(XAObject):
+ """A rule-based query detector.
+
+ .. versionadded:: 0.0.9
+ """
+ def__init__(self,finish_conditions:Union[None,dict[Callable[[str],bool],Callable[[str],bool]]]=None):
+ """Creates a speech recognizer object.
+
+ By default, with no other rules specified, the Speech Recognizer will timeout after 10 seconds once :func:`listen` is called.
+
+ :param finish_conditions: A dictionary of rules and associated methods to call when a rule evaluates to true, defaults to None
+ :type finish_conditions: Union[None, dict[Callable[[str], bool], Callable[[str], bool]]], optional
+
+ .. versionadded:: 0.0.9
+ """
+ default_conditions={
+ lambdax:self.time_elapsed>timedelta(seconds=10):lambdax:self.spoken_query,
+ }
+ self.finish_conditions:Callable[[str],bool]=finish_conditionsordefault_conditions#: A dictionary of rules and associated methods to call when a rule evaluates to true
+ self.spoken_query:str=""#: The recognized spoken input
+ self.start_time:datetime#: The time that the Speech Recognizer begins listening
+ self.time_elapsed:timedelta#: The amount of time passed since the start time
+
+ def__prepare(self):
+ # Request microphone access if we don't already have it
+ Speech.SFSpeechRecognizer.requestAuthorization_(None)
+
+ # Set up audio session
+ self.audio_session=AVFoundation.AVAudioSession.sharedInstance()
+ self.audio_session.setCategory_mode_options_error_(AVFoundation.AVAudioSessionCategoryRecord,AVFoundation.AVAudioSessionModeMeasurement,AVFoundation.AVAudioSessionCategoryOptionDuckOthers,None)
+ self.audio_session.setActive_withOptions_error_(True,AVFoundation.AVAudioSessionSetActiveOptionNotifyOthersOnDeactivation,None)
+
+ # Set up recognition request
+ self.recognizer=Speech.SFSpeechRecognizer.alloc().init()
+ self.recognition_request=Speech.SFSpeechAudioBufferRecognitionRequest.alloc().init()
+ self.recognition_request.setShouldReportPartialResults_(True)
+
+ # Set up audio engine
+ self.audio_engine=AVFoundation.AVAudioEngine.alloc().init()
+ self.input_node=self.audio_engine.inputNode()
+ recording_format=self.input_node.outputFormatForBus_(0)
+ self.input_node.installTapOnBus_bufferSize_format_block_(0,1024,recording_format,
+ lambdabuffer,_when:self.recognition_request.appendAudioPCMBuffer_(buffer))
+ self.audio_engine.prepare()
+ self.audio_engine.startAndReturnError_(None)
+
+
[docs]defon_detect(self,rule:Callable[[str],bool],method:Callable[[str],bool]):
+ """Sets the given rule to call the specified method if a spoken query passes the rule.
+
+ :param rule: A function that takes the spoken query as a parameter and returns a boolean value depending on whether the query passes a desired rule
+ :type rule: Callable[[str], bool]
+ :param method: A function that takes the spoken query as a parameter and acts on it
+ :type method: Callable[[str], bool]
+
+ .. versionadded:: 0.0.9
+ """
+ self.finish_conditions[rule]=method
+
+
[docs]deflisten(self)->Any:
+ """Begins listening for a query until a rule returns True.
+
+ :return: The value returned by the method invoked upon matching some rule
+ :rtype: Any
+
+ .. versionadded:: 0.0.9
+ """
+ self.start_time=datetime.now()
+ self.time_elapsed=None
+ self.__prepare()
+
+ old_self=self
+ defdetect_speech(transcription,error):
+ iferrorisnotNone:
+ print("Failed to detect speech. Error: ",error)
+ else:
+ old_self.spoken_query=transcription.bestTranscription().formattedString()
+ print(old_self.spoken_query)
+
+ recognition_task=self.recognizer.recognitionTaskWithRequest_resultHandler_(self.recognition_request,detect_speech)
+ whileself.spoken_query==""ornotany(x(self.spoken_query)forxinself.finish_conditions):
+ self.time_elapsed=datetime.now()-self.start_time
+ AppKit.NSRunLoop.currentRunLoop().runUntilDate_(datetime.now()+timedelta(seconds=0.5))
+
+ self.audio_engine.stop()
+ forrule,methodinself.finish_conditions.items():
+ ifrule(self.spoken_query):
+ returnmethod(self.spoken_query)
+
+
+
+
+
[docs]classXASpeech(XAObject):
+ def__init__(self,message:str="",voice:Union[str,None]=None,volume:float=0.5,rate:int=200):
+ self.message:str=message#: The message to speak
+ self.voice:Union[str,None]=voice#: The voice that the message is spoken in
+ self.volume:float=volume#: The speaking volume
+ self.rate:int=rate#: The speaking rate
+
+
[docs]defvoices(self)->list[str]:
+ """Gets the list of voice names available on the system.
+
+ :return: The list of voice names
+ :rtype: list[str]
+
+ :Example:
+
+ >>> import PyXA
+ >>> speaker = PyXA.XASpeech()
+ >>> print(speaker.voices())
+ ['Agnes', 'Alex', 'Alice', 'Allison',
+
+ .. versionadded:: 0.0.9
+ """
+ ls=AppKit.NSSpeechSynthesizer.availableVoices()
+ return[x.replace("com.apple.speech.synthesis.voice.","").replace(".premium","").title()forxinls]
+
+
[docs]defspeak(self,path:Union[str,XAPath,None]=None):
+ """Speaks the provided message using the desired voice, volume, and speaking rate.
+
+ :param path: The path to a .AIFF file to output sound to, defaults to None
+ :type path: Union[str, XAPath, None], optional
+
+ :Example 1: Speak a message aloud
+
+ >>> import PyXA
+ >>> PyXA.XASpeech("This is a test").speak()
+
+ :Example 2: Output spoken message to an AIFF file
+
+ >>> import PyXA
+ >>> speaker = PyXA.XASpeech("Hello, world!")
+ >>> speaker.speak("/Users/steven/Downloads/Hello.AIFF")
+
+ :Example 3: Control the voice, volume, and speaking rate
+
+ >>> import PyXA
+ >>> speaker = PyXA.XASpeech(
+ >>> message = "Hello, world!",
+ >>> voice = "Alex",
+ >>> volume = 1,
+ >>> rate = 500
+ >>> )
+ >>> speaker.speak()
+
+ .. versionadded:: 0.0.9
+ """
+ # Get the selected voice by name
+ voice=None
+ forvinAppKit.NSSpeechSynthesizer.availableVoices():
+ ifself.voice.lower()inv.lower():
+ voice=v
+
+ # Set up speech synthesis object
+ synthesizer=AppKit.NSSpeechSynthesizer.alloc().initWithVoice_(voice)
+ synthesizer.setVolume_(self.volume)
+ synthesizer.setRate_(self.rate)
+
+ # Start speaking
+ ifpathisNone:
+ synthesizer.startSpeakingString_(self.message)
+ else:
+ ifisinstance(path,str):
+ path=XAPath(path)
+ synthesizer.startSpeakingString_toURL_(self.message,path.xa_elem)
+
+ # Wait for speech to complete
+ whilesynthesizer.isSpeaking():
+ time.sleep(0.01)
+
+
+
+
+
[docs]classXASpotlight(XAObject):
+ """A Spotlight query for files on the disk.
+
+ .. versionadded:: 0.0.9
+ """
+ def__init__(self,*query:list[Any]):
+ self.query:list[Any]=query#: The query terms to search
+ self.timeout:int=10#: The amount of time in seconds to timeout the search after
+ self.predicate:Union[str,XAPredicate]=None#: The predicate to filter search results by
+ self.results:list[XAPath]#: The results of the search
+ self.__results=None
+
+ self.query_object=AppKit.NSMetadataQuery.alloc().init()
+ nc=AppKit.NSNotificationCenter.defaultCenter()
+ nc.addObserver_selector_name_object_(self,'_queryNotification:',None,self.query_object)
+
+ @property
+ defresults(self)->list['XAPath']:
+ iflen(self.query)==0andself.predicateisNone:
+ return[]
+ self.run()
+ total_time=0
+ whileself.__resultsisNoneandtotal_time<self.timeout:
+ AppKit.NSRunLoop.currentRunLoop().runUntilDate_(datetime.now()+timedelta(seconds=0.01))
+ total_time+=0.01
+ ifself.__resultsisNone:
+ return[]
+ returnself.__results
+
+
[docs]defrun(self):
+ """Runs the search.
+
+ :Example:
+
+ >>> import PyXA
+ >>> from datetime import date, datetime, time
+ >>> date1 = datetime.combine(date(2022, 5, 17), time(0, 0, 0))
+ >>> date2 = datetime.combine(date(2022, 5, 18), time(0, 0, 0))
+ >>> search = PyXA.XASpotlight(date1, date2)
+ >>> print(search.results)
+ [<<class 'PyXA.XAPath'>file:///Users/exampleUser/Downloads/>, <<class 'PyXA.XAPath'>file:///Users/exampleUser/Downloads/Example.txt>, ...]
+
+ .. versionadded:: 0.0.9
+ """
+ ifself.predicateisnotNone:
+ # Search with custom predicate
+ ifisinstance(self.predicate,XAPredicate):
+ self.predicate=self.predicate.get_clipboard_representation()
+ self.__search_with_predicate(self.predicate)
+ eliflen(self.query)==1andisinstance(self.query[0],datetime):
+ # Search date + or - 24 hours
+ self.__search_by_date(self.query)
+ eliflen(self.query)==2andisinstance(self.query[0],datetime)andisinstance(self.query[1],datetime):
+ # Search date range
+ self.__search_by_date_range(self.query[0],self.query[1])
+ elifall(isinstance(x,str)orisinstance(x,int)orisinstance(x,float)forxinself.query):
+ # Search matching multiple strings
+ self.__search_by_strs(self.query)
+ elifisinstance(self.query[0],datetime)andall(isinstance(x,str)orisinstance(x,int)orisinstance(x,float)forxinself.query[1:]):
+ # Search by date and string
+ self.__search_by_date_strings(self.query[0],self.query[1:])
+ elifisinstance(self.query[0],datetime)andisinstance(self.query[1],datetime)andall(isinstance(x,str)orisinstance(x,int)orisinstance(x,float)forxinself.query[2:]):
+ # Search by date range and string
+ self.__search_by_date_range_strings(self.query[0],self.query[1],self.query[2:])
+
+ AppKit.NSRunLoop.currentRunLoop().runUntilDate_(datetime.now()+timedelta(seconds=0.01))
+
+
[docs]defshow_in_finder(self):
+ """Shows the search in Finder. This might not reveal the same search results.
+
+ .. versionadded:: 0.0.9
+ """
+ AppKit.NSWorkspace.sharedWorkspace().showSearchResultsForQueryString_(str(self.query))
+
+ def__search_by_strs(self,terms:tuple[str]):
+ expanded_terms=[[x]*3forxinterms]
+ expanded_terms=[xforsublistinexpanded_termsforxinsublist]
+ format="((kMDItemDisplayName CONTAINS %@) OR (kMDItemTextContent CONTAINS %@) OR (kMDItemFSName CONTAINS %@)) AND "*len(terms)
+ self.__search_with_predicate(format[:-5],*expanded_terms)
+
+ def__search_by_date(self,date:datetime):
+ self.__search_with_predicate(f"((kMDItemContentCreationDate > %@) AND (kMDItemContentCreationDate < %@)) OR ((kMDItemContentModificationDate > %@) AND (kMDItemContentModificationDate < %@)) OR ((kMDItemFSCreationDate > %@) AND (kMDItemFSCreationDate < %@)) OR ((kMDItemFSContentChangeDate > %@) AND (kMDItemFSContentChangeDate < %@)) OR ((kMDItemDateAdded > %@) AND (kMDItemDateAdded < %@))",*[date-timedelta(hours=12),date+timedelta(hours=12)]*5)
+
+ def__search_by_date_range(self,date1:datetime,date2:datetime):
+ self.__search_with_predicate(f"((kMDItemContentCreationDate > %@) AND (kMDItemContentCreationDate < %@)) OR ((kMDItemContentModificationDate > %@) AND (kMDItemContentModificationDate < %@)) OR ((kMDItemFSCreationDate > %@) AND (kMDItemFSCreationDate < %@)) OR ((kMDItemFSContentChangeDate > %@) AND (kMDItemFSContentChangeDate < %@)) OR ((kMDItemDateAdded > %@) AND (kMDItemDateAdded < %@))",*[date1,date2]*5)
+
+ def__search_by_date_strings(self,date:datetime,terms:tuple[str]):
+ expanded_terms=[[x]*3forxinterms]
+ expanded_terms=[xforsublistinexpanded_termsforxinsublist]
+ format="((kMDItemDisplayName CONTAINS %@) OR (kMDItemTextContent CONTAINS %@) OR (kMDItemFSName CONTAINS %@)) AND "*len(terms)
+ format+="(((kMDItemContentCreationDate > %@) AND (kMDItemContentCreationDate < %@)) OR ((kMDItemContentModificationDate > %@) AND (kMDItemContentModificationDate < %@)) OR ((kMDItemFSCreationDate > %@) AND (kMDItemFSCreationDate < %@)) OR ((kMDItemFSContentChangeDate > %@) AND (kMDItemFSContentChangeDate < %@)) OR ((kMDItemDateAdded > %@) AND (kMDItemDateAdded < %@)))"
+ self.__search_with_predicate(format,*expanded_terms,*[date-timedelta(hours=12),date+timedelta(hours=12)]*5)
+
+ def__search_by_date_range_strings(self,date1:datetime,date2:datetime,terms:tuple[str]):
+ expanded_terms=[[x]*3forxinterms]
+ expanded_terms=[xforsublistinexpanded_termsforxinsublist]
+ format="((kMDItemDisplayName CONTAINS %@) OR (kMDItemTextContent CONTAINS %@) OR (kMDItemFSName CONTAINS %@)) AND "*len(terms)
+ format+="(((kMDItemContentCreationDate > %@) AND (kMDItemContentCreationDate < %@)) OR ((kMDItemContentModificationDate > %@) AND (kMDItemContentModificationDate < %@)) OR ((kMDItemFSCreationDate > %@) AND (kMDItemFSCreationDate < %@)) OR ((kMDItemFSContentChangeDate > %@) AND (kMDItemFSContentChangeDate < %@)) OR ((kMDItemDateAdded > %@) AND (kMDItemDateAdded < %@)))"
+ self.__search_with_predicate(format,*expanded_terms,*[date1,date2]*5)
+
+ def__search_with_predicate(self,predicate_format:str,*args:list[Any]):
+ predicate=AppKit.NSPredicate.predicateWithFormat_(predicate_format,*args)
+ self.query_object.setPredicate_(predicate)
+ self.query_object.startQuery()
+
+ def_queryNotification_(self,notification):
+ ifnotification.name()==AppKit.NSMetadataQueryDidFinishGatheringNotification:
+ self.query_object.stopQuery()
+ results=notification.object().results()
+ self.__results=[XAPath(x.valueForAttribute_(AppKit.NSMetadataItemPathKey))forxinresults]
[docs]classXAUIElementList(XAList):
+ """A wrapper around a list of UI elements.
+
+ All properties of UI elements can be accessed via methods on this list, returning a list of the method's return value for each element in the list.
+
+ .. versionadded:: 0.0.5
+ """
+ def__init__(self,properties:dict,filter:Union[dict,None]=None,obj_type=None):
+ ifobj_typeisNone:
+ obj_type=XAUIElement
+ super().__init__(properties,obj_type,filter)
+
+
[docs]classXAUIElement(XAObject):
+ def__init__(self,properties):
+ super().__init__(properties)
+
+ self.properties:dict#: All properties of the UI element
+ self.accessibility_description:str#: The accessibility description of the element
+ self.enabled:bool#: Whether the UI element is currently enabled
+ self.entire_contents:Any#: The entire contents of the element
+ self.focused:bool#: Whether the window is the currently element
+ self.name:str#: The name of the element
+ self.title:str#: The title of the element (often the same as its name)
+ self.position:tuple[int,int]#: The position of the top left corner of the element
+ self.size:tuple[int,int]#: The width and height of the element, in pixels
+ self.maximum_value:Any#: The maximum value that the element can have
+ self.minimum_value:Any#: The minimum value that the element can have
+ self.value:Any#: The current value of the element
+ self.role:str#: The element's role
+ self.role_description:str#: The description of the element's role
+ self.subrole:str#: The subrole of the UI element
+ self.selected:bool#: Whether the element is currently selected
+
+ @property
+ defproperties(self)->dict:
+ returnself.xa_elem.properties()
+
+ @property
+ defaccessibility_description(self)->str:
+ returnself.xa_elem.accessibilityDescription()
+
+ @property
+ defenabled(self)->bool:
+ returnself.xa_elem.enabled()
+
+ @property
+ defentire_contents(self)->list[XAObject]:
+ ls=self.xa_elem.entireContents()
+ return[self._new_element(x,XAUIElement)forxinls]
+
+ @property
+ deffocused(self)->bool:
+ returnself.xa_elem.focused()
+
+ @property
+ defname(self)->str:
+ returnself.xa_elem.name()
+
+ @property
+ deftitle(self)->str:
+ returnself.xa_elem.title()
+
+ @property
+ defposition(self)->tuple[int,int]:
+ returnself.xa_elem.position()
+
+ @property
+ defsize(self)->tuple[int,int]:
+ returnself.xa_elem.size()
+
+ @property
+ defmaximum_value(self)->Any:
+ returnself.xa_elem.maximumValue()
+
+ @property
+ defminimum_value(self)->Any:
+ returnself.xa_elem.minimumValue()
+
+ @property
+ defvalue(self)->Any:
+ returnself.xa_elem.value()
+
+ @property
+ defrole(self)->str:
+ returnself.xa_elem.role()
+
+ @property
+ defrole_description(self)->str:
+ returnself.xa_elem.roleDescription()
+
+ @property
+ defsubrole(self)->str:
+ returnself.xa_elem.subrole()
+
+ @property
+ defselected(self)->bool:
+ returnself.xa_elem.selected()
+
+
[docs]classXAWindow(XAUIElement):
+ """A general window class for windows of both officially scriptable and non-scriptable applications.
+
+ .. versionadded:: 0.0.1
+ """
+ def__init__(self,properties):
+ super().__init__(properties)
+
+
[docs]classXAUIMenuBarList(XAUIElementList):
+ """A wrapper around a list of menu bars.
+
+ .. versionadded:: 0.0.5
+ """
+ def__init__(self,properties:dict,filter:Union[dict,None]=None):
+ super().__init__(properties,filter,XAUIMenuBar)
[docs]classXAUIMenuBarItemList(XAUIElementList):
+ """A wrapper around a list of menu bar items.
+
+ .. versionadded:: 0.0.5
+ """
+ def__init__(self,properties:dict,filter:Union[dict,None]=None):
+ super().__init__(properties,filter,XAUIMenuBarItem)
[docs]classXAUIMenuList(XAUIElementList):
+ """A wrapper around a list of menus.
+
+ .. versionadded:: 0.0.5
+ """
+ def__init__(self,properties:dict,filter:Union[dict,None]=None):
+ super().__init__(properties,filter,XAUIMenu)
[docs]classXAUIMenuItemList(XAUIElementList):
+ """A wrapper around a list of menu items.
+
+ .. versionadded:: 0.0.5
+ """
+ def__init__(self,properties:dict,filter:Union[dict,None]=None):
+ super().__init__(properties,filter,XAUIMenuItem)
[docs]defclick(self)->'XAUIMenuItem':
+ """Clicks the menu item. Synonymous with :func:`press`.
+
+ :return: The menu item object.
+ :rtype: XAUIMenuItem
+
+ .. versionadded:: 0.0.2
+ """
+ self.actions({"name":"AXPress"})[0].perform()
+ returnself
+
+
[docs]defpress(self)->'XAUIMenuItem':
+ """Clicks the menu item. Synonymous with :func:`click`.
+
+ :return: The menu item object.
+ :rtype: XAUIMenuItem
+
+ .. versionadded:: 0.0.2
+ """
+ self.actions({"name":"AXPress"})[0].perform()
+ returnself
+
+
+
+
+
[docs]classXAUISplitterList(XAUIElementList):
+ """A wrapper around a list of splitters.
+
+ .. versionadded:: 0.0.8
+ """
+ def__init__(self,properties:dict,filter:Union[dict,None]=None):
+ super().__init__(properties,filter,XAUISplitter)
[docs]classXAUIToolbarList(XAUIElementList):
+ """A wrapper around a list of toolbars.
+
+ .. versionadded:: 0.0.5
+ """
+ def__init__(self,properties:dict,filter:Union[dict,None]=None):
+ super().__init__(properties,filter,XAUIToolbar)
[docs]classXAUIGroupList(XAUIElementList):
+ """A wrapper around a list of UI element groups.
+
+ .. versionadded:: 0.0.5
+ """
+ def__init__(self,properties:dict,filter:Union[dict,None]=None):
+ super().__init__(properties,filter,XAUIGroup)
+
+
[docs]classXAUIGroup(XAUIElement):
+ """A group of UI element.
+
+ .. versionadded:: 0.0.2
+ """
+ def__init__(self,properties):
+ super().__init__(properties)
+
+
+
+
+
[docs]classXAUITabGroupList(XAUIElementList):
+ """A wrapper around a list of UI element tab groups.
+
+ .. versionadded:: 0.0.5
+ """
+ def__init__(self,properties:dict,filter:Union[dict,None]=None):
+ super().__init__(properties,filter,XAUITabGroup)
[docs]defshow_menu(self)->'XAButton':
+ """Right clicks the button, invoking a menu.
+
+ :return: The button object
+ :rtype: XAButton
+
+ .. versionadded:: 0.0.2
+ """
+ self.actions({"name":"AXShowMenu"})[0].perform()
+ returnself
+
+
+
+
+
[docs]classXAUIRadioButtonList(XAUIElementList):
+ """A wrapper around lists of radio buttons that employs fast enumeration techniques.
+
+ .. versionadded:: 0.0.4
+ """
+ def__init__(self,properties:dict,filter:Union[dict,None]=None):
+ super().__init__(properties,filter,XAUIRadioButton)
[docs]classXAUIActionList(XAUIElementList):
+ """A wrapper around a list of UI element actions.
+
+ .. versionadded:: 0.0.5
+ """
+ def__init__(self,properties:dict,filter:Union[dict,None]=None):
+ super().__init__(properties,filter,XAUIAction)
[docs]classXAUITextfieldList(XAUIElementList):
+ """A wrapper around a list of textfields.
+
+ .. versionadded:: 0.0.5
+ """
+ def__init__(self,properties:dict,filter:Union[dict,None]=None):
+ super().__init__(properties,filter,XAUITextfield)
[docs]classXAUIStaticTextList(XAUIElementList):
+ """A wrapper around a list of static text elements.
+
+ .. versionadded:: 0.0.5
+ """
+ def__init__(self,properties:dict,filter:Union[dict,None]=None):
+ super().__init__(properties,filter,XAUIStaticText)
[docs]classXATextDocumentList(XAList,XAClipboardCodable):
+ """A wrapper around lists of text documents that employs fast enumeration techniques.
+
+ .. versionadded:: 0.1.0
+ """
+ def__init__(self,properties:dict,filter:Union[dict,None]=None,obj_class=None):
+ ifobj_classisNone:
+ obj_class=XATextDocument
+ super().__init__(properties,obj_class,filter)
+
+
[docs]defproperties(self)->list[dict]:
+ """Gets the properties of each document in the list.
+
+ :return: A list of document properties dictionaries
+ :rtype: list[dict]
+
+ .. versionadded:: 0.0.3
+ """
+ ls=self.xa_elem.arrayByApplyingSelector_("properties")
+ return[dict(x)forxinls]
+
+
[docs]deftext(self)->'XATextList':
+ """Gets the text of each document in the list.
+
+ :return: A list of document texts
+ :rtype: XATextList
+
+ .. versionadded:: 0.1.0
+ """
+ ls=self.xa_elem.arrayByApplyingSelector_("text")
+ returnself._new_element(ls,XATextList)
+
+
[docs]defby_properties(self,properties:dict)->Union['XATextDocument',None]:
+ """Retrieves the document whose properties match the given properties dictionary, if one exists.
+
+ :return: The desired document, if it is found
+ :rtype: Union[XATextDocument, None]
+
+ .. versionadded:: 0.1.0
+ """
+ returnself.by_property("properties",properties)
+
+
[docs]defby_text(self,text:str)->Union['XATextDocument',None]:
+ """Retrieves the first documents whose text matches the given text.
+
+ :return: The desired document, if it is found
+ :rtype: Union[XATextDocument, None]
+
+ .. versionadded:: 0.1.0
+ """
+ returnself.by_property("text",text)
+
+
[docs]defparagraphs(self)->'XAParagraphList':
+ """Gets the paragraphs of each document in the list.
+
+ :return: A combined list of all paragraphs in each document of the list
+ :rtype: XAParagraphList
+
+ .. versionadded:: 0.0.3
+ """
+ ls=self.xa_elem.arrayByApplyingSelector_("paragraphs")
+ returnself._new_element([plistforplistinls],XAParagraphList)
+
+
[docs]defwords(self)->'XAWordList':
+ """Gets the words of each document in the list.
+
+ :return: A combined list of all words in each document of the list
+ :rtype: XAWordList
+
+ .. versionadded:: 0.0.3
+ """
+ ls=self.xa_elem.arrayByApplyingSelector_("words")
+ return[self._new_element([plistforplistinls],XAWordList)]
+
+
[docs]defcharacters(self)->'XACharacterList':
+ """Gets the characters of each document in the list.
+
+ :return: A combined list of all characters in each document of the list
+ :rtype: XACharacterList
+
+ .. versionadded:: 0.0.3
+ """
+ ls=self.xa_elem.arrayByApplyingSelector_("characters")
+ return[self._new_element([plistforplistinls],XACharacterList)]
+
+
[docs]defattribute_runs(self)->'XAAttributeRunList':
+ """Gets the attribute runs of each document in the list.
+
+ :return: A combined list of all attribute runs in each document of the list
+ :rtype: XAAttributeRunList
+
+ .. versionadded:: 0.0.3
+ """
+ ls=self.xa_elem.arrayByApplyingSelector_("attributeRuns")
+ return[self._new_element([plistforplistinls],XAAttributeRunList)]
+
+
[docs]defattachments(self)->'XAAttachmentList':
+ """Gets the attachments of each document in the list.
+
+ :return: A combined list of all attachments in each document of the list
+ :rtype: XAAttachmentList
+
+ .. versionadded:: 0.0.3
+ """
+ ls=self.xa_elem.arrayByApplyingSelector_("attachments")
+ return[self._new_element([plistforplistinls],XAAttachmentList)]
+
+
[docs]defget_clipboard_representation(self)->list[Union[str,AppKit.NSURL]]:
+ """Gets a clipboard-codable representation of each document in the list.
+
+ When the clipboard content is set to a list of documents, each documents's file URL and name are added to the clipboard.
+
+ :return: A list of each document's file URL and name
+ :rtype: list[Union[str, AppKit.NSURL]]
+
+ .. versionadded:: 0.0.8
+ """
+ return[str(x)forxinself.text()]
[docs]classXATextDocument(XAObject):
+ """A class for managing and interacting with text documents.
+
+ .. versionadded:: 0.0.1
+ """
+ def__init__(self,properties):
+ super().__init__(properties)
+ self.text:XAText#: The text of the document.
+
+ @property
+ deftext(self)->'XAText':
+ returnself._new_element(self.xa_elem.text(),XAText)
+
+ @text.setter
+ deftext(self,text:str):
+ self.set_property("text",text)
+
+
[docs]defprepend(self,text:str)->'XATextDocument':
+ """Inserts the provided text at the beginning of the document.
+
+ :param text: The text to insert.
+ :type text: str
+ :return: A reference to the document object.
+ :rtype: XATextDocument
+
+ .. seealso:: :func:`append`, :func:`set_text`
+
+ .. versionadded:: 0.0.1
+ """
+ old_text=str(self.text)
+ self.set_property("text",text+old_text)
+ returnself
+
+
[docs]defappend(self,text:str)->'XATextDocument':
+ """Appends the provided text to the end of the document.
+
+ :param text: The text to append.
+ :type text: str
+ :return: A reference to the document object.
+ :rtype: XATextDocument
+
+ .. seealso:: :func:`prepend`, :func:`set_text`
+
+ .. versionadded:: 0.0.1
+ """
+ old_text=str(self.text)
+ self.set_property("text",old_text+text)
+ returnself
+
+
[docs]defreverse(self)->'XATextDocument':
+ """Reverses the text of the document.
+
+ :return: A reference to the document object.
+ :rtype: XATextDocument
+
+ .. versionadded:: 0.0.4
+ """
+ self.set_property("text",reversed(str(self.text)))
+ returnself
[docs]classXATextList(XAList):
+ """A wrapper around lists of text objects that employs fast enumeration techniques.
+
+ .. versionadded:: 0.0.4
+ """
+ def__init__(self,properties:dict,filter:Union[dict,None]=None,obj_class=None):
+ ifobj_classisNone:
+ obj_class=XAText
+ super().__init__(properties,obj_class,filter)
+
+
[docs]defparagraphs(self,filter:dict=None)->'XAParagraphList':
+ """Gets the paragraphs of every text item in the list.
+
+ :return: The list of paragraphs
+ :rtype: XAParagraphList
+
+ .. versionadded:: 0.0.1
+ """
+ ls=[]
+ ifhasattr(self.xa_elem,"get"):
+ ls=self.xa_elem.arrayByApplyingSelector_("paragraphs")
+ else:
+ ls=[x.xa_elem.split("\n")forxinself]
+ ls=[paragraphforparagraphlistinlsforparagraphinparagraphlistifparagraph.strip()!='']
+ returnself._new_element(ls,XAParagraphList,filter)
+
+
[docs]defsentences(self)->'XASentenceList':
+ """Gets the sentences of every text item in the list.
+
+ :return: The list of sentences
+ :rtype: XASentenceList
+
+ .. versionadded:: 0.1.0
+ """
+ ls=[x.sentences()forxinself]
+ ls=[sentenceforsentencelistinlsforsentenceinsentencelist]
+ returnself._new_element(ls,XASentenceList)
+
+
[docs]defwords(self,filter:dict=None)->'XAWordList':
+ """Gets the words of every text item in the list.
+
+ :return: The list of words
+ :rtype: XAWordList
+
+ .. versionadded:: 0.0.1
+ """
+ ls=[]
+ ifhasattr(self.xa_elem,"get"):
+ ls=self.xa_elem.arrayByApplyingSelector_("words")
+ else:
+ ls=[x.xa_elem.split()forxinself]
+ ls=[wordforwordlistinlsforwordinwordlist]
+ returnself._new_element(ls,XAWordList,filter)
+
+
[docs]defcharacters(self,filter:dict=None)->'XACharacterList':
+ """Gets the characters of every text item in the list.
+
+ :return: The list of characters
+ :rtype: XACharacterList
+
+ .. versionadded:: 0.0.1
+ """
+ ls=[]
+ ifhasattr(self.xa_elem,"get"):
+ ls=self.xa_elem.arrayByApplyingSelector_("characters")
+ else:
+ ls=[list(x.xa_elem)forxinself]
+ ls=[characterforcharacterlistinlsforcharacterincharacterlist]
+ returnself._new_element(ls,XACharacterList,filter)
+
+
[docs]defattribute_runs(self,filter:dict=None)->'XAAttributeRunList':
+ """Gets the attribute runs of every text item in the list.
+
+ :return: The list of attribute runs
+ :rtype: XAAttributeRunList
+
+ .. versionadded:: 0.0.1
+ """
+ ls=[]
+ ifhasattr(self.xa_elem,"get"):
+ ls=self.xa_elem.arrayByApplyingSelector_("attributeRuns")
+ ls=[attribute_runforattribute_run_listinlsforattribute_runinattribute_run_list]
+ returnself._new_element(ls,XAAttributeRunList,filter)
+
+
[docs]defattachments(self,filter:dict=None)->'XAAttachmentList':
+ """Gets the attachments of every text item in the list.
+
+ :return: The list of attachments
+ :rtype: XAAttachmentList
+
+ .. versionadded:: 0.0.1
+ """
+ ls=[]
+ ifhasattr(self.xa_elem,"get"):
+ ls=self.xa_elem.arrayByApplyingSelector_("attachments")
+ ls=[attachmentforattachment_listinlsforattachmentinattachment_list]
+ returnself._new_element(ls,XAAttachmentList,filter)
+
+ def__repr__(self):
+ try:
+ ifisinstance(self.xa_elem[0],ScriptingBridge.SBObject):
+ # List items will not resolved to text upon dereferencing the list; need to resolve items individually
+ count=self.xa_elem.count()
+ ifcount<=500:
+ # Too many unresolved pointers, save time by just reporting the length
+ return"<"+str(type(self))+str([x.get()forxinself.xa_elem])+">"
+ return"<"+str(type(self))+"length: "+str(self.xa_elem.count())+">"
+
+ # List items will resolve to text upon dereferencing the list
+ return"<"+str(type(self))+str(self.xa_elem.get())+">"
+ except:
+ return"<"+str(type(self))+str(list(self.xa_elem))+">"
+
+
[docs]classXAText(XAObject):
+ """A class for managing and interacting with the text of documents.
+
+ .. versionadded:: 0.0.1
+ """
+ def__init__(self,properties):
+ ifisinstance(properties,dict):
+ super().__init__(properties)
+ elifisinstance(properties,str):
+ super().__init__({"element":properties})
+
+ self.text:str#: The plaintext contents of the rich text
+ self.color:XAColor#: The color of the first character
+ self.font:str#: The name of the font of the first character
+ self.size:int#: The size in points of the first character
+
+ @property
+ deftext(self)->str:
+ ifisinstance(self.xa_elem,str):
+ returnself.xa_elem
+ else:
+ returnself.xa_elem.text()
+
+ @text.setter
+ deftext(self,text:str):
+ ifisinstance(self.xa_elem,str):
+ self.xa_elem=text
+ else:
+ self.set_property("text",text)
+
+ @property
+ defcolor(self)->'XAColor':
+ ifisinstance(self.xa_elem,str):
+ returnNone
+ else:
+ returnXAColor(self.xa_elem.color())
+
+ @color.setter
+ defcolor(self,color:'XAColor'):
+ ifisinstance(self.xa_elem,str):
+ self.color=color.xa_elem
+ else:
+ self.set_property("color",color.xa_elem)
+
+ @property
+ deffont(self)->str:
+ ifisinstance(self.xa_elem,str):
+ returnNone
+ else:
+ returnself.xa_elem.font()
+
+ @font.setter
+ deffont(self,font:str):
+ ifisinstance(self.xa_elem,str):
+ self.font=font
+ else:
+ self.set_property("font",font)
+
+ @property
+ defsize(self)->int:
+ ifisinstance(self.xa_elem,str):
+ return0
+ else:
+ returnself.xa_elem.size()
+
+ @size.setter
+ defsize(self,size:int):
+ ifisinstance(self.xa_elem,str):
+ self.size=size
+ else:
+ self.set_property("size",size)
+
+ # def spelling_suggestions(self):
+ # suggestions = []
+ # text = str(self.xa_elem)
+ # spellchecker = AppKit.NSSpellChecker.sharedSpellChecker()
+
+ # orthography = None
+ # word_count = 0
+
+ # pprint(dir(LatentSemanticMapping.LSMMapCreate(None, 0)))
+
+ # # c = spellchecker.checkString_range_types_options_inSpellDocumentWithTag_orthography_wordCount_(text, (0, len(text)), AppKit.NSTextCheckingTypeSpelling | AppKit.NSTextCheckingTypeGrammar | AppKit.NSTextCheckingTypeCorrection, {}, 0, orthography, None)
+ # # print(c[1].languageMap())
+
+ # for word in text.split():
+ # completions = spellchecker.completionsForPartialWordRange_inString_language_inSpellDocumentWithTag_((0, len(word)), word, "", 0)
+ # suggestions.append(completions)
+
+ # # for word in text.split():
+ # # guesses = spellchecker.guessesForWordRange_inString_language_inSpellDocumentWithTag_((0, len(word)), word, "", 0)
+ # # suggestions.append(guesses)
+ # return suggestions
+
+
[docs]deftag_parts_of_speech(self,unit:Literal["word","sentence","paragraph","document"]="word")->list[tuple[str,str]]:
+ """Tags each word of the text with its associated part of speech.
+
+ :param unit: The grammatical unit to divide the text into for tagging, defaults to "word"
+ :type unit: Literal["word", "sentence", "paragraph", "document"]
+ :return: A list of tuples identifying each word of the text and its part of speech
+ :rtype: list[tuple[str, str]]
+
+ :Example 1: Extract nouns from a text
+
+ >>> import PyXA
+ >>> text = PyXA.XAText("Here’s to the crazy ones. The misfits. The rebels.")
+ >>> nouns = [pos[0] for pos in text.tag_parts_of_speech() if pos[1] == "Noun"]
+ >>> print(nouns)
+ ['ones', 'misfits', 'rebels']
+
+ .. versionadded:: 0.1.0
+ """
+ tagger=NaturalLanguage.NLTagger.alloc().initWithTagSchemes_([NaturalLanguage.NLTagSchemeLexicalClass])
+ tagger.setString_(str(self.xa_elem))
+
+ ifunit=="word":
+ unit=NaturalLanguage.NLTokenUnitWord
+ elifunit=="sentence":
+ unit=NaturalLanguage.NLTokenUnitSentence
+ elifunit=="paragraph":
+ unit=NaturalLanguage.NLTokenUnitParagraph
+ elifunit=="document":
+ unit=NaturalLanguage.NLTokenUnitDocument
+
+ tagged_pos=[]
+ defapply_tags(tag,token_range,error):
+ word_phrase=str(self.xa_elem)[token_range.location:token_range.location+token_range.length]
+ tagged_pos.append((word_phrase,tag))
+
+ tagger.enumerateTagsInRange_unit_scheme_options_usingBlock_((0,len(str(self.xa_elem))),unit,NaturalLanguage.NLTagSchemeLexicalClass,NaturalLanguage.NLTaggerOmitPunctuation|NaturalLanguage.NLTaggerOmitWhitespace,apply_tags)
+ returntagged_pos
+
+
[docs]deftag_languages(self,unit:Literal["word","sentence","paragraph","document"]="paragraph")->list[tuple[str,str]]:
+ """Tags each paragraph of the text with its language.
+
+ :param unit: The grammatical unit to divide the text into for tagging, defaults to "paragraph"
+ :type unit: Literal["word", "sentence", "paragraph", "document"]
+ :return: A list of tuples identifying each paragraph of the text and its language
+ :rtype: list[tuple[str, str]]
+
+ :Example:
+
+ >>> import PyXA
+ >>> text = PyXA.XAText("This is English.\nQuesto è Italiano.\nDas ist deutsch.\nこれは日本語です。")
+ >>> print(text.tag_languages())
+ [('This is English.\n', 'en'), ('Questo è Italiano.\n', 'it'), ('Das ist deutsch.\n', 'de'), ('これは日本語です。', 'ja')]
+
+ .. versionadded:: 0.1.0
+ """
+ tagger=NaturalLanguage.NLTagger.alloc().initWithTagSchemes_([NaturalLanguage.NLTagSchemeLanguage])
+ tagger.setString_(str(self.xa_elem))
+
+ ifunit=="word":
+ unit=NaturalLanguage.NLTokenUnitWord
+ elifunit=="sentence":
+ unit=NaturalLanguage.NLTokenUnitSentence
+ elifunit=="paragraph":
+ unit=NaturalLanguage.NLTokenUnitParagraph
+ elifunit=="document":
+ unit=NaturalLanguage.NLTokenUnitDocument
+
+ tagged_languages=[]
+ defapply_tags(tag,token_range,error):
+ paragraph=str(self.xa_elem)[token_range.location:token_range.location+token_range.length]
+ ifparagraph.strip()!="":
+ tagged_languages.append((paragraph,tag))
+
+ tagger.enumerateTagsInRange_unit_scheme_options_usingBlock_((0,len(str(self.xa_elem))),unit,NaturalLanguage.NLTagSchemeLanguage,NaturalLanguage.NLTaggerOmitPunctuation|NaturalLanguage.NLTaggerOmitWhitespace,apply_tags)
+ returntagged_languages
+
+
[docs]deftag_entities(self,unit:Literal["word","sentence","paragraph","document"]="word")->list[tuple[str,str]]:
+ """Tags each word of the text with either the category of entity it represents (i.e. person, place, or organization) or its part of speech.
+
+ :param unit: The grammatical unit to divide the text into for tagging, defaults to "word"
+ :type unit: Literal["word", "sentence", "paragraph", "document"]
+ :return: A list of tuples identifying each word of the text and its entity category or part of speech
+ :rtype: list[tuple[str, str]]
+
+ :Example:
+
+ >>> import PyXA
+ >>> text = PyXA.XAText("Tim Cook is the CEO of Apple.")
+ >>> print(text.tag_entities())
+ [('Tim', 'PersonalName'), ('Cook', 'PersonalName'), ('is', 'Verb'), ('the', 'Determiner'), ('CEO', 'Noun'), ('of', 'Preposition'), ('Apple', 'OrganizationName')]
+
+ .. versionadded:: 0.1.0
+ """
+ tagger=NaturalLanguage.NLTagger.alloc().initWithTagSchemes_([NaturalLanguage.NLTagSchemeNameTypeOrLexicalClass])
+ tagger.setString_(str(self.xa_elem))
+
+ ifunit=="word":
+ unit=NaturalLanguage.NLTokenUnitWord
+ elifunit=="sentence":
+ unit=NaturalLanguage.NLTokenUnitSentence
+ elifunit=="paragraph":
+ unit=NaturalLanguage.NLTokenUnitParagraph
+ elifunit=="document":
+ unit=NaturalLanguage.NLTokenUnitDocument
+
+ tagged_languages=[]
+ defapply_tags(tag,token_range,error):
+ word_phrase=str(self.xa_elem)[token_range.location:token_range.location+token_range.length]
+ ifword_phrase.strip()!="":
+ tagged_languages.append((word_phrase,tag))
+
+ tagger.enumerateTagsInRange_unit_scheme_options_usingBlock_((0,len(str(self.xa_elem))),unit,NaturalLanguage.NLTagSchemeNameTypeOrLexicalClass,NaturalLanguage.NLTaggerOmitPunctuation|NaturalLanguage.NLTaggerOmitWhitespace,apply_tags)
+ returntagged_languages
+
+
[docs]deftag_lemmas(self,unit:Literal["word","sentence","paragraph","document"]="word")->list[tuple[str,str]]:
+ """Tags each word of the text with its stem word.
+
+ :param unit: The grammatical unit to divide the text into for tagging, defaults to "word"
+ :type unit: Literal["word", "sentence", "paragraph", "document"]
+ :return: A list of tuples identifying each word of the text and its stem words
+ :rtype: list[tuple[str, str]]
+
+ :Example 1: Lemmatize each word in a text
+
+ >>> import PyXA
+ >>> text = PyXA.XAText("Here’s to the crazy ones. The misfits. The rebels.")
+ >>> print(text.tag_lemmas())
+ [('Here’s', 'here'), ('to', 'to'), ('the', 'the'), ('crazy', 'crazy'), ('ones', 'one'), ('The', 'the'), ('misfits', 'misfit'), ('The', 'the'), ('rebels', 'rebel')]
+
+ :Example 2: Combine parts of speech tagging and lemmatization
+
+ >>> import PyXA
+ >>> text = PyXA.XAText("The quick brown fox tries to jump over the sleeping lazy dog.")
+ >>> verbs = [pos[0] for pos in text.tag_parts_of_speech() if pos[1] == "Verb"]
+ >>> for index, verb in enumerate(verbs):
+ >>> print(index, PyXA.XAText(verb).tag_lemmas())
+ 0 [('tries', 'try')]
+ 1 [('jump', 'jump')]
+ 2 [('sleeping', 'sleep')]
+
+ .. versionadded:: 0.1.0
+ """
+ tagger=NaturalLanguage.NLTagger.alloc().initWithTagSchemes_([NaturalLanguage.NLTagSchemeLemma])
+ tagger.setString_(str(self.xa_elem))
+
+ ifunit=="word":
+ unit=NaturalLanguage.NLTokenUnitWord
+ elifunit=="sentence":
+ unit=NaturalLanguage.NLTokenUnitSentence
+ elifunit=="paragraph":
+ unit=NaturalLanguage.NLTokenUnitParagraph
+ elifunit=="document":
+ unit=NaturalLanguage.NLTokenUnitDocument
+
+ tagged_lemmas=[]
+ defapply_tags(tag,token_range,error):
+ word_phrase=str(self.xa_elem)[token_range.location:token_range.location+token_range.length]
+ ifword_phrase.strip()!="":
+ tagged_lemmas.append((word_phrase,tag))
+
+ tagger.enumerateTagsInRange_unit_scheme_options_usingBlock_((0,len(str(self.xa_elem))),unit,NaturalLanguage.NLTagSchemeLemma,NaturalLanguage.NLTaggerOmitPunctuation|NaturalLanguage.NLTaggerOmitWhitespace|NaturalLanguage.NLTaggerJoinContractions,apply_tags)
+ returntagged_lemmas
+
+
[docs]deftag_sentiments(self,sentiment_scale:list[str]=None,unit:Literal["word","sentence","paragraph","document"]="paragraph")->list[tuple[str,str]]:
+ """Tags each paragraph of the text with a sentiment rating.
+
+ :param sentiment_scale: A list of terms establishing a range of sentiments from most negative to most postive
+ :type sentiment_scale: list[str]
+ :param unit: The grammatical unit to divide the text into for tagging, defaults to "paragraph"
+ :type unit: Literal["word", "sentence", "paragraph", "document"]
+ :return: A list of tuples identifying each paragraph of the text and its sentiment rating
+ :rtype: list[tuple[str, str]]
+
+ :Example 1: Assess the sentiment of a string
+
+ >>> import PyXA
+ >>> text = PyXA.XAText("This sucks.\nBut this is great!")
+ >>> print(text.tag_sentiments())
+ [('This sucks.\n', 'Negative'), ('But this is great!', 'Positive')]
+
+ :Example 2: Use a custom sentiment scale
+
+ >>> import PyXA
+ >>> text = PyXA.XAText("This sucks.\nBut this is good!\nAnd this is great!")
+ >>> print(text.tag_sentiments(sentiment_scale=["Very Negative", "Negative", "Somewhat Negative", "Neutral", "Somewhat Positive", "Positive", "Very Positive"]))
+ [('This sucks.\n', 'Very Negative'), ('But this is good!\n', 'Neutral'), ('And this is great!', 'Very Positive')]
+
+ :Example 3: Use other tag units
+
+ >>> import PyXA
+ >>> text = PyXA.XAText("This sucks.\nBut this is good!\nAnd this is great!")
+ >>> print(1, text.tag_sentiments())
+ >>> print(2, text.tag_sentiments(unit="word"))
+ >>> print(3, text.tag_sentiments(unit="document"))
+ 1 [('This sucks.\n', 'Negative'), ('But this is good!\n', 'Neutral'), ('And this is great!', 'Positive')]
+ 2 [('This', 'Negative'), ('sucks', 'Negative'), ('.', 'Negative'), ('But', 'Neutral'), ('this', 'Neutral'), ('is', 'Neutral'), ('good', 'Neutral'), ('!', 'Neutral'), ('And', 'Positive'), ('this', 'Positive'), ('is', 'Positive'), ('great', 'Positive'), ('!', 'Positive')]
+ 3 [('This sucks.\nBut this is good!\nAnd this is great!', 'Neutral')]
+
+ .. versionadded:: 0.1.0
+ """
+ ifsentiment_scaleisNoneorlen(sentiment_scale)==0:
+ sentiment_scale=["Negative","Neutral","Positive"]
+
+ ifunit=="word":
+ unit=NaturalLanguage.NLTokenUnitWord
+ elifunit=="sentence":
+ unit=NaturalLanguage.NLTokenUnitSentence
+ elifunit=="paragraph":
+ unit=NaturalLanguage.NLTokenUnitParagraph
+ elifunit=="document":
+ unit=NaturalLanguage.NLTokenUnitDocument
+
+ tagger=NaturalLanguage.NLTagger.alloc().initWithTagSchemes_([NaturalLanguage.NLTagSchemeSentimentScore])
+ tagger.setString_(str(self.xa_elem))
+
+ tagged_sentiments=[]
+ defapply_tags(tag,token_range,error):
+ paragraph=str(self.xa_elem)[token_range.location:token_range.location+token_range.length]
+ ifparagraph.strip()!="":
+ # Map raw tag value to range length
+ raw_value=float(tagor0)
+ scaled=(raw_value+1.0)/2.0*(len(sentiment_scale)-1)
+
+ label=sentiment_scale[int(scaled)]
+ tagged_sentiments.append((paragraph,label))
+
+ tagger.enumerateTagsInRange_unit_scheme_options_usingBlock_((0,len(self.xa_elem)),unit,NaturalLanguage.NLTagSchemeSentimentScore,0,apply_tags)
+ returntagged_sentiments
+
+
[docs]defparagraphs(self,filter:dict=None)->'XAParagraphList':
+ """Gets a list of paragraphs in the text.
+
+ :param filter: The properties and associated values to filter paragraphs by, defaults to None
+ :type filter: dict, optional
+ :return: The list of paragraphs
+ :rtype: XAParagraphList
+
+ :Example 1: Get paragraphs of a text string
+
+ >>> import PyXA
+ >>> string = \"\"\"This is the first paragraph.
+ >>>
+ >>> This is the second paragraph.\"\"\"
+ >>> text = PyXA.XAText(string)
+ >>> print(text.paragraphs())
+ <<class 'PyXA.XAWordList'>['This is the first paragraph.', 'This is the second paragraph. Neat! Very cool.']>
+
+ :Example 2: Get paragraphs of a Note
+
+ >>> import PyXA
+ >>> app = PyXA.Application("Notes")
+ >>> note = app.notes()[0]
+ >>> text = PyXA.XAText(note.plaintext)
+ >>> print(text.paragraphs())
+ <<class 'PyXA.XAWordList'>['This is the first paragraph.', 'This is the second paragraph. Neat! Very cool.']>
+
+ .. versionadded:: 0.0.1
+ """
+ ifisinstance(self.xa_elem,str):
+ ls=[xforxinself.xa_elem.split("\n")ifx.strip()!='']
+ returnself._new_element(ls,XAWordList,filter)
+ else:
+ returnself._new_element(self.xa_elem.paragraphs(),XAParagraphList,filter)
+
+
[docs]defsentences(self)->'XASentenceList':
+ """Gets a list of sentences in the text.
+
+ :return: The list of sentencnes
+ :rtype: XASentenceList
+
+ :Example:
+
+ >>> import PyXA
+ >>> app = PyXA.Application("Notes")
+ >>> note = app.notes()[0]
+ >>> text = PyXA.XAText(note.plaintext)
+ >>> print(text.sentences())
+ <<class 'PyXA.XASentenceList'>['This is the first paragraph.\\n', '\\n', 'This is the second paragraph. ', 'Neat! ', 'Very cool.']>
+
+ .. versionadded:: 0.1.0
+ """
+ raw_string=self.xa_elem
+ ifhasattr(self.xa_elem,"get"):
+ raw_string=self.xa_elem.get()
+
+ sentences=[]
+ tokenizer=AppKit.NLTokenizer.alloc().initWithUnit_(AppKit.kCFStringTokenizerUnitSentence)
+ tokenizer.setString_(raw_string)
+ forchar_rangeintokenizer.tokensForRange_((0,len(raw_string))):
+ start=char_range.rangeValue().location
+ end=start+char_range.rangeValue().length
+ sentences.append(raw_string[start:end])
+
+ ls=AppKit.NSArray.alloc().initWithArray_(sentences)
+ returnself._new_element(sentences,XASentenceList)
+
+
[docs]defwords(self,filter:dict=None)->'XAWordList':
+ """Gets a list of words in the text.
+
+ :return: The list of words
+ :rtype: XAWordList
+
+ :Example:
+
+ >>> import PyXA
+ >>> app = PyXA.Application("Notes")
+ >>> note = app.notes()[0]
+ >>> text = PyXA.XAText(note.plaintext)
+ >>> print(text.words())
+ <<class 'PyXA.XAWordList'>['This', 'is', 'the', 'first', 'paragraph.', 'This', 'is', 'the', 'second', 'paragraph.', 'Neat!', 'Very', 'cool.']>
+
+ .. versionadded:: 0.0.1
+ """
+ ifisinstance(self.xa_elem,str):
+ ls=self.xa_elem.split()
+ returnself._new_element(ls,XAWordList,filter)
+ else:
+ returnself._new_element(self.xa_elem.words(),XAWordList,filter)
+
+
[docs]defcharacters(self,filter:dict=None)->'XACharacterList':
+ """Gets a list of characters in the text.
+
+ :return: The list of characters
+ :rtype: XACharacterList
+
+ :Example 1: Get all characters in a text
+
+ >>> import PyXA
+ >>> app = PyXA.Application("Notes")
+ >>> note = app.notes()[0]
+ >>> text = PyXA.XAText(note.plaintext)
+ >>> print(text.characters())
+ <<class 'PyXA.XACharacterList'>['T', 'h', 'i', 's', ' ', 'i', 's', ' ', 't', 'h', 'e', ' ', 'f', 'i', 'r', 's', 't', ' ', 'p', 'a', 'r', 'a', 'g', 'r', 'a', 'p', 'h', '.', '\n', '\n', 'T', 'h', 'i', 's', ' ', 'i', 's', ' ', 't', 'h', 'e', ' ', 's', 'e', 'c', 'o', 'n', 'd', ' ', 'p', 'a', 'r', 'a', 'g', 'r', 'a', 'p', 'h', '.', ' ', 'N', 'e', 'a', 't', '!', ' ', 'V', 'e', 'r', 'y', ' ', 'c', 'o', 'o', 'l', '.']>
+
+ :Example 2: Get the characters of the first word in a text
+
+ >>> import PyXA
+ >>> app = PyXA.Application("Notes")
+ >>> note = app.notes()[0]
+ >>> text = PyXA.XAText(note.plaintext)
+ >>> print(text.words()[0].characters())
+ <<class 'PyXA.XACharacterList'>['T', 'h', 'i', 's']>
+
+ .. versionadded:: 0.0.1
+ """
+ ifisinstance(self.xa_elem,str):
+ ls=list(self.xa_elem)
+ returnself._new_element(ls,XACharacterList,filter)
+ else:
+ returnself._new_element(self.xa_elem.characters().get(),XACharacterList,filter)
+
+
[docs]defattribute_runs(self,filter:dict=None)->'XAAttributeRunList':
+ """Gets a list of attribute runs in the text. For formatted text, this returns all sequences of characters sharing the same attributes.
+
+ :param filter: The properties and associated values to filter attribute runs by, defaults to None
+ :type filter: dict, optional
+ :return: The list of attribute runs
+ :rtype: XAAttributeRunList
+
+ .. versionadded:: 0.0.1
+ """
+ ifisinstance(self.xa_elem,str):
+ return[]
+ else:
+ returnself._new_element(self.xa_elem.attributeRuns(),XAAttributeRunList,filter)
+
+
[docs]defattachments(self,filter:dict=None)->'XAAttachmentList':
+ """Gets a list of attachments of the text.
+
+ :param filter: The properties and associated values to filter attachments by, defaults to None
+ :type filter: dict, optional
+ :return: The list of attachments
+ :rtype: XAAttachmentList
+
+ .. versionadded:: 0.0.1
+ """
+ ifisinstance(self.xa_elem,str):
+ return[]
+ else:
+ returnself._new_element(self.xa_elem.attachments(),XAAttachmentList,filter)
[docs]classXAParagraphList(XATextList):
+ """A wrapper around lists of paragraphs that employs fast enumeration techniques.
+
+ .. versionadded:: 0.0.5
+ """
+ def__init__(self,properties:dict,filter:Union[dict,None]=None):
+ super().__init__(properties,filter,XAParagraph)
+
+
[docs]classXAParagraph(XAText):
+ """A class for managing and interacting with paragraphs in text documents.
+
+ .. versionadded:: 0.0.1
+ """
+ def__init__(self,properties):
+ super().__init__(properties)
+
+
+
+
[docs]classXASentenceList(XATextList):
+ """A wrapper around lists of sentences that employs fast enumeration techniques.
+
+ .. versionadded:: 0.0.5
+ """
+ def__init__(self,properties:dict,filter:Union[dict,None]=None):
+ super().__init__(properties,filter,XASentence)
+
+
[docs]classXASentence(XAText):
+ """A class for managing and interacting with sentences in text documents.
+
+ .. versionadded:: 0.0.1
+ """
+ def__init__(self,properties):
+ super().__init__(properties)
+
+
+
+
+
[docs]classXAWordList(XATextList):
+ """A wrapper around lists of words that employs fast enumeration techniques.
+
+ .. versionadded:: 0.0.5
+ """
+ def__init__(self,properties:dict,filter:Union[dict,None]=None):
+ super().__init__(properties,filter,XAWord)
+
+
[docs]classXAWord(XAText):
+ """A class for managing and interacting with words in text documents.
+
+ .. versionadded:: 0.0.1
+ """
+ def__init__(self,properties):
+ super().__init__(properties)
+
+
+
+
+
[docs]classXACharacterList(XATextList):
+ """A wrapper around lists of characters that employs fast enumeration techniques.
+
+ .. versionadded:: 0.0.5
+ """
+ def__init__(self,properties:dict,filter:Union[dict,None]=None):
+ super().__init__(properties,filter,XACharacter)
+
+
[docs]classXACharacter(XAText):
+ """A class for managing and interacting with characters in text documents.
+
+ .. versionadded:: 0.0.1
+ """
+ def__init__(self,properties):
+ super().__init__(properties)
+
+
+
+
+
[docs]classXAAttributeRunList(XATextList):
+ """A wrapper around lists of attribute runs that employs fast enumeration techniques.
+
+ .. versionadded:: 0.0.5
+ """
+ def__init__(self,properties:dict,filter:Union[dict,None]=None):
+ super().__init__(properties,filter,XAAttributeRun)
+
+
[docs]classXAAttributeRun(XAText):
+ """A class for managing and interacting with attribute runs in text documents.
+
+ .. versionadded:: 0.0.1
+ """
+ def__init__(self,properties):
+ super().__init__(properties)
+
+
+
+
+
[docs]classXAAttachmentList(XATextList):
+ """A wrapper around lists of text attachments that employs fast enumeration techniques.
+
+ .. versionadded:: 0.0.5
+ """
+ def__init__(self,properties:dict,filter:Union[dict,None]=None):
+ super().__init__(properties,filter,XAAttachment)
+
+
[docs]classXAAttachment(XAObject):
+ """A class for managing and interacting with attachments in text documents.
+
+ .. versionadded:: 0.0.1
+ """
+ def__init__(self,properties):
+ super().__init__(properties)
+
+
+
+
+
[docs]classXALSM(XAObject):
+ def__init__(self,dataset:Union[dict[str,list[str]],None]=None,from_file:bool=False):
+ """Initializes a Latent Semantic Mapping environment.
+
+ :param dataset: The initial dataset, specified as a dictionary where keys are categories and values are list of corresponding texts, defaults to None. Cannot be None if from_file is False.
+ :type dataset: Union[dict[str, list[str]], None], optional
+ :param from_file: Whether the LSM is being loaded from a file, defaults to False. Cannot be False is dataset is None.
+ :type from_file: bool, optional
+ :raises ValueError: Either you must provide a dataset, or you must load an existing map from an external file
+
+ :Example 1: Classify emails based on subject line
+
+ >>> import PyXA
+ >>> lsm = PyXA.XALSM({
+ >>> # 1
+ >>> "spam": ["Deals", "Holiday playbook", "Spend and save. You know the drill.", "Don't miss these holiday deals!", "GOOD NEWS", "you will never have an opportunity of this kind again", "Your Long Overdue Compensation Funds; Totally", "US $25,000,000.00", "goog day", "GOOD DAY, I am Mike Paul I have a", "enron methanol; meter # : 988291 this is a follow up to the note i gave you on monday , 4...", "hpl nom for january 9, see attached file : hplnol 09. xls", "neon retreat ho ho ho, we're around to that most wonderful time of the year", "photoshop, windows, office cheap, main trending abasements, darer prudently fortuitous", "re: indian springs this deal is to book the teco pvr revenue. it is my understanding that...", "noms / actual flow for 2 / we agree", "nominations for oct 21 - 23"],
+ >>>
+ >>> # 2
+ >>> "kayak": ["Price Alert: Airfare holding steady for your trip", "Prices going down for your Boston to Dublin flight", "Price Increase: Boston to Dublin airfare up $184", "Flight Alert: #37 decrease on your flight to Dublin.", "Flight Alert: It's time to book your flight to Dublin", "Price Alert: Airfare holding steady for your Bangor, ME to...", "Ready to explore the world again?"],
+ >>>
+ >>> # 3
+ >>> "lenovo": ["Doorbuster deals up to 70% off", "Visionary, On-Demand Content. Lenovo Tech World '22 is starting", "Up to 70% off deals 9 AM", "TGIF! Here's up to 70% off to jumpstart your weekend", "Top picks to refresh your workspace", "This only happens twice a year", "Think about saving on a Think PC", "Deep deals on Summer Clearance", "Save up to 67% + earn rewards", "Unlock up to 61% off Think PCs", "Giveaway alert!", "Annual Sale Sneak Peak Unlocked!"],
+ >>>
+ >>> # 4
+ >>> "linkedin": ["Here is the latest post trending amongst your coworkers", "Stephen, add Sean Brown to your network", "Share thoughts on LinkedIn", "Top companies are hiring", "Linkedin is better on the app", "Here is the latest post trending amongst your coworkers", "Stephen, add Ronald McDonald to your network", "James Smith shared a post for the first time in a while", "Here is the latest post trending amongst your coworkers", "You appeared in 13 searches this week", "you're on a roll with your career!", "You appeared in 16 searches this week", "18 people notices you", "You appeared in 10 searches this week", "Stephen, add Joe Shmoe to your network", "Your network is talking: The Center for Oceanic Research...", "thanks for being a valued member"]
+ >>> })
+ >>> print(lsm.categorize_query("New! Weekend-only deals"))
+ >>> print(lsm.categorize_query("Stephen, redeem these three (3) unlocked courses"))
+ >>> print(lsm.categorize_query("Round Trip From San Francisco to Atlanta"))
+ [(3, 0.9418474435806274)]
+ [(4, 0.9366401433944702)]
+ [(2, 0.9944692850112915)]
+
+ :Example 2: Use the Mail module to automate dataset construction
+
+ >>> import PyXA
+ >>> app = PyXA.Application("Mail")
+ >>> junk_subject_lines = app.accounts()[0].mailboxes().by_name("Junk").messages().subject()
+ >>> other_subject_lines = app.accounts()[0].mailboxes().by_name("INBOX").messages().subject()
+ >>>
+ >>> dataset = {
+ >>> "junk": junk_subject_lines,
+ >>> "other": other_subject_lines
+ >>> }
+ >>> lsm = PyXA.XALSM(dataset)
+ >>>
+ >>> query = "Amazon Web Services Billing Statement Available"
+ >>> category = list(dataset.keys())[lsm.categorize_query(query)[0][0] - 1]
+ >>> print(query, "- category:", category)
+ >>>
+ >>> query = "Complete registration form asap receive your rewards"
+ >>> category = list(dataset.keys())[lsm.categorize_query(query)[0][0] - 1]
+ >>> print(query, "- category:", category)
+ Amazon Web Services Billing Statement Available - category: other
+ Complete registration form asap receive your rewards - category: junk
+
+ .. versionadded:: 0.1.0
+ """
+ self.__categories={}
+ ifdatasetisNoneandnotfrom_file:
+ raiseValueError("You must either load a map from an external file or provide an initial dataset.")
+ elifdatasetisNone:
+ # Map will be loaded from external file -- empty dataset is temporary
+ self.__dataset={}
+ else:
+ # Create new map
+ self.__dataset=dataset
+
+ self.map=LatentSemanticMapping.LSMMapCreate(None,0)
+ LatentSemanticMapping.LSMMapStartTraining(self.map)
+ LatentSemanticMapping.LSMMapSetProperties(self.map,{
+ LatentSemanticMapping.kLSMSweepCutoffKey:0,
+ # LatentSemanticMapping.kLSMPrecisionKey: LatentSemanticMapping.kLSMPrecisionDouble,
+ LatentSemanticMapping.kLSMAlgorithmKey:LatentSemanticMapping.kLSMAlgorithmSparse,
+ })
+
+ forcategoryindataset:
+ self.__add_category(category)
+
+ LatentSemanticMapping.LSMMapCompile(self.map)
+
+ def__add_category(self,category:str)->int:
+ loc=Foundation.CFLocaleGetSystem()
+ category_ref=LatentSemanticMapping.LSMMapAddCategory(self.map)
+ self.__categories[category]=category_ref
+ self.__categories[category_ref]=category_ref
+ text_ref=LatentSemanticMapping.LSMTextCreate(None,self.map)
+ LatentSemanticMapping.LSMTextAddWords(text_ref," ".join(self.__dataset[category]),loc,LatentSemanticMapping.kLSMTextPreserveAcronyms)
+ LatentSemanticMapping.LSMMapAddText(self.map,text_ref,category_ref)
+ returncategory_ref
+
+
[docs]defsave(self,file_path:Union[XAPath,str])->bool:
+ """Saves the map to an external file.
+
+ :param file_path: The path to save the map at
+ :type file_path: Union[XAPath, str]
+ :return: True if the map was saved successfully
+ :rtype: bool
+
+ :Example: Create a Reddit post classifier for gaming vs. productivity posts
+
+ >>> import PyXA
+ >>> lsm = PyXA.XALSM({
+ >>> # 1
+ >>> "gaming": ["If you could vote on the 2017 Mob Vote again, which mob would you choose this time and why?", "Take your time, you got this", "My parents (late 70s) got me a ps5 controller for Christmas. I do not own a playstation 5...", "I got off the horse by accident right before a cutscene in red dead", "boy gamer", "Minesweeper 99 x 99, 1500 mines. Took me about 2.5 hours to finish, nerve-wracking. No one might care, but just wanted to share this.", "The perfect cosplay doesn’t ex...", "'Play until we lose'", "Can we please boycott Star Wars battlefront 2", "EA removed the refund button on their webpage, and now you have to call them and wait to get a refund.", "Train Simulator is so immersive!", "Been gaming with this dude for 15 years. Since Rainbow Six Vegas on 360. I have some good gaming memories with him. He tried but couldn’t get one. Little did he know I was able to get him one. Looking forward to playing another generation with him.", "EA will no longer have exclusive rights of the Star Wars games", "A ziplining contraption I created with 1000+ command blocks", "The steepest walkable staircase possible in 1.16", "I made a texture pack that gives mobs different facial expressions. Should I keep going?"],
+ >>>
+ >>> # 2
+ >>> "productivity": ["Looking for an alarm app that plays a really small alarm, doesn’t need to be switched off and doesn’t repeat.", "I want to build a second brain but I'm lost and don't know where to start.", "noise cancelling earplugs", "I have so much to do but I don't know where to start", "How to handle stressful work calls", "time tracking app/platform", "We just need to find ways to cope and keep moving forward.", "Ikigai - A Reason for Being", "Minimalist Productivity Tip: create two users on your computer ➞ One for normal use and leisure ➞ One for business/work only. I have nothing except the essentials logged in on my work user. Not even Messages or YouTube. It completely revolutionized my productivity 💸", "Trick yourself into productivity the same way you trick yourself into procrastination", "I spent 40 hours sifting through research papers to fix my mental clarity, focus, and productivity - I ended up going down a rabbit hole and figuring out it was all tied to sleep, even though I felt I sleep well - here's what I found.", "The Cycle of Procrastination. Always a good reminder", "'Most people underestimate what they can do in a year, and overestimate what they can do in a day' - When you work on getting 1% better each day you won't even recognize yourself in a year."],
+ >>> })
+ >>> lsm.save("/Users/steven/Downloads/gaming-productivity.map")
+
+ .. versionadded:: 0.1.0
+ """
+ ifisinstance(file_path,str):
+ file_path=XAPath(file_path)
+
+ status=LatentSemanticMapping.LSMMapWriteToURL(self.map,file_path.xa_elem,0)
+ ifstatus==0:
+ returnTrue
+ returnFalse
+
+
[docs]defload(file_path:Union[XAPath,str])->'XALSM':
+ """Loads a map from an external file.
+
+ :param file_path: The file path for load the map from
+ :type file_path: Union[XAPath, str]
+ :return: The populated LSM object
+ :rtype: XALSM
+
+ :Example: Using the gaming vs. productivity Reddit post map
+
+ >>> import PyXA
+ >>> lsm = PyXA.XALSM.load("/Users/steven/Downloads/gaming-productivity.map")
+ >>> print(lsm.categorize_query("Hidden survival base on our server"))
+ >>> print(lsm.categorize_query("Your memory is FAR more powerful than you think… school just never taught us to use it properly."))
+ [(1, 0.7313863635063171)]
+ [(2, 0.9422407150268555)]
+
+ .. versionadded:: 0.1.0
+ """
+ ifisinstance(file_path,str):
+ file_path=XAPath(file_path)
+
+ new_lsm=XALSM(from_file=True)
+ new_lsm.map=LatentSemanticMapping.LSMMapCreateFromURL(None,file_path.xa_elem,LatentSemanticMapping.kLSMMapLoadMutable)
+ new_lsm.__dataset={i:[]foriinrange(LatentSemanticMapping.LSMMapGetCategoryCount(new_lsm.map))}
+ new_lsm.__categories={i:iforiinrange(LatentSemanticMapping.LSMMapGetCategoryCount(new_lsm.map))}
+ LatentSemanticMapping.LSMMapCompile(new_lsm.map)
+ returnnew_lsm
+
+
[docs]defadd_category(self,name:str,initial_data:Union[list[str],None]=None)->int:
+ """Adds a new category to the map, optionally filling the category with initial text data.
+
+ :param name: The name of the category
+ :type name: str
+ :param initial_data: _description_
+ :type initial_data: list[str]
+ :return: The ID of the new category
+ :rtype: int
+
+ :Example: Add a category for cleaning-related Reddit posts to the previous example
+
+ >>> import PyXA
+ >>> lsm = PyXA.XALSM.load("/Users/steven/Downloads/gaming-productivity.map")
+ >>> lsm.add_category("cleaning", ["Curtains stained from eyelet reaction at dry cleaner", "How do I get these stains out of my pink denim overalls? from a black denim jacket that was drying next to them", "Cleaned my depression room after months 🥵", "Tip: 30 minute soak in Vinegar", "Regular floor squeegee pulled a surprising amount of pet hair out of my carpet!", "Before and after…", "It actually WORKS", "CLR is actually magic. (With some elbow grease)", "It was 100% worth it to scrape out my old moldy caulk and replace it. $5 dollars and a bit of time to make my shower look so much cleaner!", "Thanks to the person who recommended the Clorox Foamer. Before and after pics", "TIL you can dissolve inkstains with milk.", "Fixing cat scratch marks to couch using felting needle: Before and After", "Turns out BKF isn't a meme! Really satisfied with this stuff"])
+ >>> print(lsm.categorize_query("Hidden survival base on our server"))
+ >>> print(lsm.categorize_query("Your memory is FAR more powerful than you think… school just never taught us to use it properly."))
+ >>> print(lsm.categorize_query("A carpet rake will change your life."))
+ [(1, 0.7474805116653442)]
+ [(2, 0.7167008519172668)]
+ [(3, 0.797333300113678)]
+
+ .. versionadded:: 0.1.0
+ """
+ LatentSemanticMapping.LSMMapStartTraining(self.map)
+
+ ifinitial_dataisNone:
+ initial_data=[]
+
+ ifnameinself.__dataset:
+ raiseValueError("The category name must be unique.")
+
+ self.__dataset[name]=initial_data
+ category_ref=self.__add_category(name)
+ LatentSemanticMapping.LSMMapCompile(self.map)
+ returncategory_ref
+
+
[docs]defadd_data(self,data:dict[Union[int,str],list[str]])->list[int]:
+ """Adds the provided data, organized by category, to the active map.
+
+ :param data: A dictionary specifying new or existing categories along with data to input into them
+ :type data: dict[Union[int, str], list[str]]
+ :return: A list of newly created category IDs
+ :rtype: int
+
+ :Example: Classify text by language
+
+ >>> import PyXA
+ >>> lsm = PyXA.XALSM({})
+ >>> lsm.add_data({
+ >>> # 1
+ >>> "english": ["brilliance outer jacket artist flat mosquito recover restrict official gas ratio publish domestic realize pure offset obstacle thigh favorite demonstration revive nest reader slide pudding symptom ballot auction characteristic complete Mars ridge student explosion dive emphasis the buy perfect motif penny a errand to fur far spirit random integration of with"],
+ >>>
+ >>> # 2
+ >>> "italian": ["da piazza proposta di legge legare nazionale a volte la salute bar farti farmi il pane aggiunta valore artista chiamata settentrionale scuro buio classe signori investitore in grado di fidanzato tagliare arriva successo altrimenti speciale esattamente definizione sorriso chiamo madre pulire esperto rurale vedo malattia era amici libertà l'account immaginare lingua soldi più perché"],
+ >>> })
+ >>> print(lsm.categorize_query("Here's to the crazy ones"))
+ >>> print(lsm.categorize_query("Potete parlarmi in italiano"))
+ [(1, 1.0)]
+ [(2, 1.0)]
+
+ .. versionadded:: 0.1.0
+ """
+ category_refs=[]
+ LatentSemanticMapping.LSMMapStartTraining(self.map)
+ forcategoryindata:
+ ifcategorynotinself.__dataset:
+ self.__dataset[category]=data[category]
+ category_refs.append(self.__add_category(category))
+ else:
+ loc=Foundation.CFLocaleGetSystem()
+ text_ref=LatentSemanticMapping.LSMTextCreate(None,self.map)
+ LatentSemanticMapping.LSMTextAddWords(text_ref," ".join(data[category]),loc,LatentSemanticMapping.kLSMTextPreserveAcronyms)
+ LatentSemanticMapping.LSMMapAddText(self.map,text_ref,self.__categories[category])
+ LatentSemanticMapping.LSMMapCompile(self.map)
+ returncategory_refs
+
+
[docs]defadd_text(self,text:str,category:Union[int,str],weight:float=1):
+ """Adds the given text to the specified category, applying an optional weight.
+
+ :param text: The text to add to the dataset
+ :type text: str
+ :param category: The category to add the text to
+ :type category: Union[int, str]
+ :param weight: The weight to assign to the text entry, defaults to 1
+ :type weight: float, optional
+ :raises ValueError: The specified category must be a valid category name or ID
+
+ :Example:
+
+ >>> import PyXA
+ >>> lsm = PyXA.XALSM({"colors": [], "numbers": ["One", "Two", "Three"]})
+ >>> lsm.add_text("red orange yellow green blue purple", "colors")
+ >>> lsm.add_text("white black grey gray brown pink", 1)
+ >>> print(lsm.categorize_query("pink"))
+
+ .. versionadded:: 0.1.0
+ """
+ LatentSemanticMapping.LSMMapStartTraining(self.map)
+ ifcategorynotinself.__datasetandcategorynotinself.__categories:
+ raiseValueError(f"Invalid category: {category}")
+
+ loc=Foundation.CFLocaleGetSystem()
+ text_ref=LatentSemanticMapping.LSMTextCreate(None,self.map)
+ LatentSemanticMapping.LSMTextAddWords(text_ref,text,loc,LatentSemanticMapping.kLSMTextPreserveAcronyms)
+ LatentSemanticMapping.LSMMapAddTextWithWeight(self.map,text_ref,self.__categories[category],weight)
+ LatentSemanticMapping.LSMMapCompile(self.map)
+
+
[docs]defcategorize_query(self,query:str,num_results:int=1)->list[tuple[int,float]]:
+ """Categorizes the query based on the current weights in the map.
+
+ :param query: The query to categorize
+ :type query: str
+ :param num_results: The number of categorizations to show, defaults to 1
+ :type num_results: int, optional
+ :return: A list of tuples identifying categories and their associated score. A higher score indicates better fit. If not matching categorization is found, the list will be empty.
+ :rtype: list[tuple[int, float]]
+
+ :Example:
+
+ >>> import PyXA
+ >>> dataset = {
+ >>> # 1
+ >>> "color": ["red", "orange", "yellow", "green", "emerald", "blue", "purple", "white", "black", "brown", "pink", "grey", "gray"],
+ >>>
+ >>> # 2
+ >>> "number": ["One Two Three Four Five Six Seven Eight Nine Ten"]
+ >>> }
+ >>> lsm = PyXA.XALSM(dataset)
+ >>> queries = ["emerald green three", "one hundred five", "One o' clock", "sky blue", "ninety nine", "purple pink"]
+ >>>
+ >>> for query in queries:
+ >>> category = "Unknown"
+ >>> categorization_tuple = lsm.categorize_query(query)
+ >>> if len(categorization_tuple) > 0:
+ >>> category = list(dataset.keys())[categorization_tuple[0][0] - 1]
+ >>> print(query, "is a", category)
+ emerald green three is a color
+ one hundred five is a number
+ One o' clock is a number
+ sky blue is a color
+ ninety nine is a number
+ purple pink is a color
+
+ .. versionadded:: 0.1.0
+ """
+ loc=Foundation.CFLocaleGetSystem()
+ text_ref=LatentSemanticMapping.LSMTextCreate(None,self.map)
+ LatentSemanticMapping.LSMTextAddWords(text_ref,query,loc,0)
+ rows=LatentSemanticMapping.LSMResultCreate(None,self.map,text_ref,10,LatentSemanticMapping.kLSMTextPreserveAcronyms)
+
+ categorization=[]
+ num_results=min(num_results,LatentSemanticMapping.LSMResultGetCount(rows))
+ foriinrange(0,num_results):
+ category_num=LatentSemanticMapping.LSMResultGetCategory(rows,i)
+ score=LatentSemanticMapping.LSMResultGetScore(rows,i)
+ categorization.append((category_num,score))
+ returncategorization
+
+
+
+
+
[docs]classXAColorList(XATextList):
+ """A wrapper around lists of colors that employs fast enumeration techniques.
+
+ .. versionadded:: 0.0.6
+ """
+ def__init__(self,properties:dict,filter:Union[dict,None]=None):
+ super().__init__(properties,XAColor,filter)
+
+
[docs]classXAColor(XAObject,XAClipboardCodable):
+ def__init__(self,*args):
+ iflen(args)==0:
+ # No color specified -- default to white
+ self.xa_elem=XAColor.white_color().xa_elem
+ eliflen(args)==1andisinstance(args[0],AppKit.NSColor):
+ # Initialize copy of non-mutable NSColor object
+ self.copy_color(args[0])
+ eliflen(args)==1andisinstance(args[0],XAColor):
+ # Initialize copy of another XAColor object
+ self.copy_color(args[0].xa_elem)
+ else:
+ # Initialize from provided RGBA values
+ red=args[0]iflen(args)>=0else255
+ green=args[1]iflen(args)>=1else255
+ blue=args[2]iflen(args)>=3else255
+ alpha=args[3]iflen(args)==4else1.0
+ self.xa_elem=AppKit.NSCalibratedRGBColor.alloc().initWithRed_green_blue_alpha_(red,green,blue,alpha)
+
+
[docs]defred()->'XAColor':
+ """Initializes and returns a pure red :class:`XAColor` object.
+
+ .. versionadded:: 0.1.0
+ """
+ returnXAColor(65535,0,0)
+
+
[docs]deforange()->'XAColor':
+ """Initializes and returns an :class:`XAColor` object whose RGB values are (1.0, 0.5, 0.0).
+
+ .. versionadded:: 0.1.0
+ """
+ returnXAColor(AppKit.NSColor.orangeColor())
+
+
[docs]defyellow()->'XAColor':
+ """Initializes and returns an :class:`XAColor` object whose RGB values are (1.0, 1.0, 0.0).
+
+ .. versionadded:: 0.1.0
+ """
+ returnXAColor(AppKit.NSColor.yellowColor())
+
+
[docs]defgreen()->'XAColor':
+ """Initializes and returns a pure green :class:`XAColor` object.
+
+ .. versionadded:: 0.1.0
+ """
+ returnXAColor(0,65535,0)
+
+
[docs]defcyan()->'XAColor':
+ """Initializes and returns an :class:`XAColor` object whose RGB values are (0.0, 1.0, 1.0).
+
+ .. versionadded:: 0.1.0
+ """
+ returnXAColor(AppKit.NSColor.cyanColor())
+
+
[docs]defblue()->'XAColor':
+ """Initializes and returns a pure blue :class:`XAColor` object.
+
+ .. versionadded:: 0.1.0
+ """
+ returnXAColor(0,0,65535)
+
+
[docs]defmagenta()->'XAColor':
+ """Initializes and returns an :class:`XAColor` object whose RGB values are (1.0, 0.0, 1.0).
+
+ .. versionadded:: 0.1.0
+ """
+ returnXAColor(AppKit.NSColor.magentaColor())
+
+
[docs]defpurple()->'XAColor':
+ """Initializes and returns an :class:`XAColor` object whose RGB values are (0.5, 0.0, 0.5).
+
+ .. versionadded:: 0.1.0
+ """
+ returnXAColor(AppKit.NSColor.purpleColor())
+
+
[docs]defbrown()->'XAColor':
+ """Initializes and returns an :class:`XAColor` object whose RGB values are (0.6, 0.4, 0.2).
+
+ .. versionadded:: 0.1.0
+ """
+ returnXAColor(AppKit.NSColor.brownColor())
+
+
[docs]defwhite()->'XAColor':
+ """Initializes and returns a pure white :class:`XAColor` object.
+
+ .. versionadded:: 0.1.0
+ """
+ returnXAColor(65535,65535,65535)
+
+
[docs]defgray()->'XAColor':
+ """Initializes and returns an :class:`XAColor` object whose RGB values are (0.5, 0.5, 0.5).
+
+ .. versionadded:: 0.1.0
+ """
+ returnXAColor(0.5,0.5,0.5)
+
+
[docs]defblack()->'XAColor':
+ """Initializes and returns a pure black :class:`XAColor` object.
+
+ .. versionadded:: 0.1.0
+ """
+ returnXAColor(0,0,0)
+
+
[docs]defclear()->'XAColor':
+ """Initializes and returns a an :class:`XAColor` object whose alpha value is 0.0.
+
+ .. versionadded:: 0.1.0
+ """
+ returnXAColor(0,0,0,0)
+
+ @property
+ defred_value(self)->float:
+ """The red value of the color on the scale of 0.0 to 1.0.
+
+ .. versionadded:: 0.1.0
+ """
+ returnself.xa_elem.redComponent()
+
+ @red_value.setter
+ defred_value(self,red_value:float):
+ self.xa_elem=AppKit.NSCalibratedRGBColor.alloc().initWithRed_green_blue_alpha_(red_value,self.green_value,self.blue_value,self.alpha_value)
+
+ @property
+ defgreen_value(self)->float:
+ """The green value of the color on the scale of 0.0 to 1.0.
+
+ .. versionadded:: 0.1.0
+ """
+ returnself.xa_elem.greenComponent()
+
+ @green_value.setter
+ defgreen_value(self,green_value:float):
+ self.xa_elem=AppKit.NSCalibratedRGBColor.alloc().initWithRed_green_blue_alpha_(self.red_value,green_value,self.blue_value,self.alpha_value)
+
+ @property
+ defblue_value(self)->float:
+ """The blue value of the color on the scale of 0.0 to 1.0.
+
+ .. versionadded:: 0.1.0
+ """
+ returnself.xa_elem.blueComponent()
+
+ @blue_value.setter
+ defblue_value(self,blue_value:float):
+ self.xa_elem=AppKit.NSCalibratedRGBColor.alloc().initWithRed_green_blue_alpha_(self.red_value,self.green_value,blue_value,self.alpha_value)
+
+ @property
+ defalpha_value(self)->float:
+ """The alpha value of the color on the scale of 0.0 to 1.0.
+
+ .. versionadded:: 0.1.0
+ """
+ returnself.xa_elem.alphaComponent()
+
+ @alpha_value.setter
+ defalpha_value(self,alpha_value:float):
+ self.xa_elem=AppKit.NSCalibratedRGBColor.alloc().initWithRed_green_blue_alpha_(self.red_value,self.green_value,self.blue_value,alpha_value)
+
+ @property
+ defhue_value(self):
+ """The hue value of the color on the scale of 0.0 to 1.0.
+
+ .. versionadded:: 0.1.0
+ """
+ returnself.xa_elem.hueComponent()
+
+ @hue_value.setter
+ defhue_value(self,hue_value:float):
+ self.xa_elem=AppKit.NSCalibratedRGBColor.initWithHue_saturation_brightness_alpha_(hue_value,self.saturation_value,self.brightness_value,self.alpha_value)
+
+ @property
+ defsaturation_value(self):
+ """The staturation value of the color on the scale of 0.0 to 1.0.
+
+ .. versionadded:: 0.1.0
+ """
+ returnself.xa_elem.saturationComponent()
+
+ @saturation_value.setter
+ defsaturation_value(self,saturation_value:float):
+ self.xa_elem=AppKit.NSCalibratedRGBColor.initWithHue_saturation_brightness_alpha_(self.hue_value,saturation_value,self.brightness_value,self.alpha_value)
+
+ @property
+ defbrightness_value(self):
+ """The brightness value of the color on the scale of 0.0 to 1.0.
+
+ .. versionadded:: 0.1.0
+ """
+ returnself.xa_elem.brightnessComponent()
+
+ @brightness_value.setter
+ defbrightness_value(self,brightness_value:float):
+ self.xa_elem=AppKit.NSCalibratedRGBColor.initWithHue_saturation_brightness_alpha_(self.hue_value,self.saturation_value,brightness_value,self.alpha_value)
+
+
[docs]defcopy_color(self,color:AppKit.NSColor)->'XAColor':
+ """Initializes a XAColor copy of an NSColor object.
+
+ :param color: The NSColor to copy
+ :type color: AppKit.NSColor
+ :return: The newly created XAColor object
+ :rtype: XAColor
+
+ .. versionadded:: 0.1.0
+ """
+ self.xa_elem=AppKit.NSCalibratedRGBColor.alloc().initWithRed_green_blue_alpha_(
+ color.redComponent(),
+ color.greenComponent(),
+ color.blueComponent(),
+ color.alphaComponent()
+ )
+ returnself
+
+
[docs]defset_rgba(self,red:float,green:float,blue:float,alpha:float)->'XAColor':
+ """Sets the RGBA values of the color.
+
+ :param red: The red value of the color, from 0.0 to 1.0
+ :type red: float
+ :param green: The green value of the color, from 0.0 to 1.0
+ :type green: float
+ :param blue: The blue value of the color, from 0.0 to 1.0
+ :type blue: float
+ :param alpha: The opacity of the color, from 0.0 to 1.0
+ :type alpha: float
+ :return: The XAColor object
+ :rtype: XAColor
- .. versionadded:: 0.0.8
+ .. versionadded:: 0.1.0 """
- image_types=[AppKit.NSPasteboardTypePNG,AppKit.NSPasteboardTypeTIFF,'public.jpeg','com.apple.icns']
- items=[]
- foriteminself.xa_elem.pasteboardItems():
- forimage_typeinimage_types:
- ifimage_typeinitem.types():
- img=XAImage(data=item.dataForType_(image_type))
- items.append(img)
- returnitems
[docs]defset_contents(self,content:List[Any]):
- """Sets the content of the clipboard
+
[docs]defset_hsla(self,hue:float,saturation:float,brightness:float,alpha:float)->'XAColor':
+ """Sets the HSLA values of the color.
+
+ :param hue: The hue value of the color, from 0.0 to 1.0
+ :type hue: float
+ :param saturation: The saturation value of the color, from 0.0 to 1.0
+ :type saturation: float
+ :param brightness: The brightness value of the color, from 0.0 to 1.0
+ :type brightness: float
+ :param alpha: The opacity of the color, from 0.0 to 1.0
+ :type alpha: float
+ :return: The XAColor object
+ :rtype: XAColor
- :param content: A list of the content to add fill the clipboard with.
- :type content: List[Any]
+ .. versionadded:: 0.1.0
+ """
+ self.xa_elem=AppKit.NSCalibratedRGBColor.initWithHue_saturation_brightness_alpha_(hue,saturation,brightness,alpha)
+ returnself
- .. deprecated:: 0.0.8
- Set the :ivar:`content` property directly instead.
-
- .. versionadded:: 0.0.5
+
[docs]defmix_with(self,color:'XAColor',fraction:int=0.5)->'XAColor':
+ """Blends this color with the specified fraction of another.
+
+ :param color: The color to blend this color with
+ :type color: XAColor
+ :param fraction: The fraction of the other color to mix into this color, from 0.0 to 1.0, defaults to 0.5
+ :type fraction: int, optional
+ :return: The resulting color after mixing
+ :rtype: XAColor
+
+ .. versionadded:: 0.1.0 """
- self.xa_elem.clearContents()
- self.xa_elem.writeObjects_(content)
[docs]defbrighten(self,fraction:float=0.5)->'XAColor':
+ """Brightens the color by mixing the specified fraction of the system white color into it.
+ :param fraction: The amount (fraction) of white to mix into the color, defaults to 0.5
+ :type fraction: float, optional
+ :return: The resulting color after brightening
+ :rtype: XAColor
+ .. versionadded:: 0.1.0
+ """
+ self.xa_elem=self.xa_elem.highlightWithLevel_(fraction)
+ returnself
-
[docs]classXANotification(XAObject):
- """A class for managing and interacting with notifications.
+
[docs]defdarken(self,fraction:float=0.5)->'XAColor':
+ """Darkens the color by mixing the specified fraction of the system black color into it.
- .. versionadded:: 0.0.9
- """
- def__init__(self,text:str,title:Union[str,None]=None,subtitle:Union[str,None]=None,sound_name:Union[str,None]=None):
- """Initializes a notification object.
+ :param fraction: The amount (fraction) of black to mix into the color, defaults to 0.5
+ :type fraction: float, optional
+ :return: The resulting color after darkening
+ :rtype: XAColor
- :param text: The main text of the notification
- :type text: str
- :param title: The title of the notification, defaults to None
- :type title: Union[str, None], optional
- :param subtitle: The subtitle of the notification, defaults to None
- :type subtitle: Union[str, None], optional
- :param sound_name: The sound to play when the notification is displayed, defaults to None
- :type sound_name: Union[str, None], optional
+ .. versionadded:: 0.1.0
+ """
+ self.xa_elem=self.xa_elem.shadowWithLevel_(fraction)
+ returnself
- .. versionadded:: 0.0.9
+
[docs]defmake_swatch(self,width:int=100,height:int=100)->'XAImage':
+ """Creates an image swatch of the color with the specified dimensions.
+
+ :param width: The width of the swatch image, in pixels, defaults to 100
+ :type width: int, optional
+ :param height: The height of the swatch image, in pixels, defaults to 100
+ :type height: int, optional
+ :return: The image swatch as an XAImage object
+ :rtype: XAImage
+
+ :Example: View swatches in Preview
+
+ >>> import PyXA
+ >>> from time import sleep
+ >>>
+ >>> blue = PyXA.XAColor.blue()
+ >>> red = PyXA.XAColor.red()
+ >>>
+ >>> swatches = [
+ >>> blue.make_swatch(),
+ >>> blue.darken(0.5).make_swatch(),
+ >>> blue.mix_with(red).make_swatch()
+ >>> ]
+ >>>
+ >>> for swatch in swatches:
+ >>> swatch.show_in_preview()
+ >>> sleep(0.2)
+
+ .. versionadded:: 0.1.0 """
- self.text=text
- self.title=title
- self.subtitle=subtitle
- self.sound_name=sound_name
+ img=AppKit.NSImage.alloc().initWithSize_(AppKit.NSMakeSize(width,height))
+ img.lockFocus()
+ self.xa_elem.drawSwatchInRect_(AppKit.NSMakeRect(0,0,width,height))
+ img.unlockFocus()
+ returnXAImage(img)
-
[docs]defdisplay(self):
- """Displays the notification.
+
[docs]defget_clipboard_representation(self)->AppKit.NSColor:
+ """Gets a clipboard-codable representation of the color.
- .. todo::
-
- Currently uses :func:`subprocess.Popen`. Should use UserNotifications in the future.
+ When the clipboard content is set to a color, the raw color data is added to the clipboard.
- .. versionadded:: 0.0.9
+ :return: The raw color data
+ :rtype: AppKit.NSColor
+
+ .. versionadded:: 0.1.0 """
- script=AppleScript()
- script.add(f"display notification \\\"{self.text}\\\"")
+ returnself.xa_elem
[docs]classXALocation(XAObject):
+ """A location with a latitude and longitude, along with other data.
+
+ .. versionadded:: 0.0.2
+ """
+ current_location:'XALocation'#: The current location of the device
+
+ def__init__(self,raw_value:CoreLocation.CLLocation=None,title:str=None,latitude:float=0,longitude:float=0,altitude:float=None,radius:int=0,address:str=None):
+ self.raw_value=raw_value#: The raw CLLocation object
+ self.title=title#: The name of the location
+ self.latitude=latitude#: The latitude of the location
+ self.longitude=longitude#: The longitude of the location
+ self.altitude=altitude#: The altitude of the location
+ self.radius=radius#: The horizontal accuracy of the location measurement
+ self.address=address#: The addres of the location
+
+ @property
+ defraw_value(self)->CoreLocation.CLLocation:
+ returnself.__raw_value
+
+ @raw_value.setter
+ defraw_value(self,raw_value:CoreLocation.CLLocation):
+ self.__raw_value=raw_value
+ ifraw_valueisnotNone:
+ self.latitude=raw_value.coordinate()[0]
+ self.longitude=raw_value.coordinate()[1]
+ self.altitude=raw_value.altitude()
+ self.radius=raw_value.horizontalAccuracy()
+
+ @property
+ defcurrent_location(self)->'XALocation':
+ self.raw_value=None
+ self._spawn_thread(self.__get_current_location)
+ whileself.raw_valueisNone:
+ time.sleep(0.01)
+ returnself
+
+
[docs]defshow_in_maps(self):
+ """Shows the location in Maps.app.
+
+ .. versionadded:: 0.0.6
+ """
+ XAURL(f"maps://?q={self.title},ll={self.latitude},{self.longitude}").open()
[docs]classXAAlertStyle(Enum):
+ """Options for which alert style an alert should display with.
+ """
+ INFORMATIONAL=AppKit.NSAlertStyleInformational
+ WARNING=AppKit.NSAlertStyleWarning
+ CRITICAL=AppKit.NSAlertStyleCritical
+
+
[docs]classXAAlert(XAObject):
+ """A class for creating and interacting with an alert dialog window.
+
+ .. versionadded:: 0.0.5
+ """
+ def__init__(self,title:str="Alert!",message:str="",style:XAAlertStyle=XAAlertStyle.INFORMATIONAL,buttons=["Ok","Cancel"]):
+ super().__init__()
+ self.title:str=title
+ self.message:str=message
+ self.style:XAAlertStyle=style
+ self.buttons:list[str]=buttons
+
+
[docs]defdisplay(self)->int:
+ """Displays the alert.
+
+ :return: A number representing the button that the user selected, if any
+ :rtype: int
+
+ .. versionadded:: 0.0.5
+ """
+ alert=AppKit.NSAlert.alloc().init()
+ alert.setMessageText_(self.title)
+ alert.setInformativeText_(self.message)
+ alert.setAlertStyle_(self.style.value)
+
+ forbuttoninself.buttons:
+ alert.addButtonWithTitle_(button)
+ returnalert.runModal()
+
+
+
+
+
[docs]classXAColorPickerStyle(Enum):
+ """Options for which tab a color picker should display when first opened.
+ """
+ GRAYSCALE=AppKit.NSColorPanelModeGray
+ RGB_SLIDERS=AppKit.NSColorPanelModeRGB
+ CMYK_SLIDERS=AppKit.NSColorPanelModeCMYK
+ HSB_SLIDERS=AppKit.NSColorPanelModeHSB
+ COLOR_LIST=AppKit.NSColorPanelModeColorList
+ COLOR_WHEEL=AppKit.NSColorPanelModeWheel
+ CRAYONS=AppKit.NSColorPanelModeCrayon
+ IMAGE_PALETTE=AppKit.NSColorPanelModeCustomPalette
+
+
[docs]classXAColorPicker(XAObject):
+ """A class for creating and interacting with a color picker window.
+
+ .. versionadded:: 0.0.5
+ """
+ def__init__(self,style:XAColorPickerStyle=XAColorPickerStyle.GRAYSCALE):
+ super().__init__()
+ self.style=style
+
+
[docs]defdisplay(self)->XAColor:
+ """Displays the color picker.
+
+ :return: The color that the user selected
+ :rtype: XAColor
+
+ .. versionadded:: 0.0.5
+ """
+ panel=AppKit.NSColorPanel.sharedColorPanel()
+ panel.setMode_(self.style.value)
+ panel.setShowsAlpha_(True)
+
+ defrun_modal(panel):
+ initial_color=panel.color()
+ time.sleep(0.5)
+ whilepanel.isVisible()andpanel.color()==initial_color:
+ time.sleep(0.01)
+ AppKit.NSApp.stopModal()
+
+ modal_thread=threading.Thread(target=run_modal,args=(panel,),name="Run Modal",daemon=True)
+ modal_thread.start()
+
+ AppKit.NSApp.runModalForWindow_(panel)
+ returnXAColor(panel.color())
[docs]defdisplay(self)->Union[str,int,None,list[str]]:
+ """Displays the dialog, waits for the user to select an option or cancel, then returns the selected button or None if cancelled.
- cmd="osascript -e \""+" ".join(script.script)+"\""
- subprocess.Popen([cmd],shell=True)
+ :return: The selected button or None if no value was selected
+ :rtype: Union[str, int, None, list[str]]
+ .. versionadded:: 0.0.8
+ """
+ buttons=[x.replace("'","")forxinself.buttons]
+ buttons=str(buttons).replace("'",'"')
+ default_button=str(self.default_button).replace("'","")
+ default_button_str="default button \""+default_button+"\""ifself.default_buttonisnotNoneelse""
+ cancel_button=str(self.cancel_button).replace("'","")
+ cancel_button_str="cancel button \""+cancel_button+"\""ifself.cancel_buttonisnotNoneelse""
-
[docs]classXAList(XAObject):
- """A wrapper around NSArray and NSMutableArray objects enabling fast enumeration and lazy evaluation of Objective-C objects.
+ icon_str="with icon "+self.icon+""ifself.iconisnotNoneelse""
- .. versionadded:: 0.0.3
- """
- def__init__(self,properties:dict,object_class:type=None,filter:Union[dict,None]=None):
- """Creates an efficient wrapper object around a list of scriptable elements.
+ default_answer=str(self.default_answer).replace("'",'"')
+ default_answer_str="default answer \""+default_answer+"\""ifself.default_answerisnotNoneelse""
- :param properties: PyXA properties passed to this object for utility purposes
- :type properties: dict
- :param object_class: _description_, defaults to None
- :type object_class: type, optional
- :param filter: A dictionary of properties and values to filter items by, defaults to None
- :type filter: Union[dict, None], optional
+ script=AppleScript(f"""
+ tell application "Terminal"
+ display dialog \"{self.text}\" with title \"{self.title}\" buttons {buttons}{default_button_str}{cancel_button_str}{icon_str}{default_answer_str} hidden answer {self.hidden_answer}
+ end tell
+ """)
- .. versionchanged:: 0.0.8
- The filter property is deprecated and will be removed in a future version. Use the :func:`filter` method instead.
+ result=script.run()["event"]
+ ifresultisnotNone:
+ ifresult.numberOfItems()>1:
+ return[result.descriptorAtIndex_(1).stringValue(),result.descriptorAtIndex_(2).stringValue()]
+ else:
+ returnresult.descriptorAtIndex_(1).stringValue()
[docs]defby_property(self,property:str,value:Any)->XAObject:
- """Retrieves the first element whose property value matches the given value, if one exists.
+
[docs]classXAMenu(XAObject):
+ """A custom list item selection menu.
- :param property: The property to match
- :type property: str
- :param value: The value to match
- :type value: Any
- :return: The matching element, if one is found
- :rtype: XAObject
+ .. versionadded:: 0.0.8
+ """
+ def__init__(self,menu_items:list[Any],title:str="Select Item",prompt:str="Select an item",default_items:Union[list[str],None]=None,ok_button_name:str="Okay",cancel_button_name:str="Cancel",multiple_selections_allowed:bool=False,empty_selection_allowed:bool=False):
+ super().__init__()
+ self.menu_items:list[Union[str,int]]=menu_items#: The items the user can choose from
+ self.title:str=title#: The title of the dialog window
+ self.prompt:str=prompt#: The prompt to display in the dialog box
+ self.default_items:list[str]=default_itemsor[]#: The items to initially select
+ self.ok_button_name:str=ok_button_name#: The name of the OK button
+ self.cancel_button_name:str=cancel_button_name#: The name of the Cancel button
+ self.multiple_selections_allowed:bool=multiple_selections_allowed#: Whether multiple items can be selected
+ self.empty_selection_allowed:bool=empty_selection_allowed#: Whether the user can click OK without selecting anything
- :Example:
+
[docs]defdisplay(self)->Union[str,int,bool,list[str],list[int]]:
+ """Displays the menu, waits for the user to select an option or cancel, then returns the selected value or False if cancelled.
- >>> 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>
+ :return: The selected value or False if no value was selected
+ :rtype: Union[str, int, bool, list[str], list[int]]
- .. versionadded:: 0.0.6
+ .. versionadded:: 0.0.8 """
- predicate=XAPredicate()
- predicate.add_eq_condition(property,value)
- ls=predicate.evaluate(self.xa_elem)
- obj=ls[0]
- returnself._new_element(obj,self.xa_ocls)
+ menu_items=[x.replace("'","")forxinself.menu_items]
+ menu_items=str(menu_items).replace("'",'"')
+ default_items=str(self.default_items).replace("'",'"')
+ script=AppleScript(f"""
+ tell application "Terminal"
+ choose from list {menu_items} with title \"{self.title}\" with prompt \"{self.prompt}\" default items {default_items} OK button name \"{self.ok_button_name}\" cancel button name \"{self.cancel_button_name}\" multiple selections allowed {self.multiple_selections_allowed} empty selection allowed {self.empty_selection_allowed}
+ end tell
+ """)
+ result=script.run()["event"]
+ ifresultisnotNone:
+ ifself.multiple_selections_allowed:
+ values=[]
+ forxinrange(1,result.numberOfItems()+1):
+ desc=result.descriptorAtIndex_(x)
+ values.append(desc.stringValue())
+ returnvalues
+ else:
+ ifresult.stringValue()=="false":
+ returnFalse
+ returnresult.stringValue()
-
[docs]defcontaining(self,property:str,value:str)->XAObject:
- """Retrieves the element whose property value contains the given value, if one exists.
- :param property: The property match
- :type property: str
- :param value: The value to search for
- :type value: str
- :return: The matching element, if one is found
- :rtype: XAObject
- .. deprecated:: 0.0.8
- Use :func:`filter` instead.
- .. versionadded:: 0.0.6
- """
- predicate=XAPredicate()
- predicate.add_contains_condition(property,value)
- ls=predicate.evaluate(self.xa_elem)
- obj=ls[0]
- returnself._new_element(obj,self.xa_ocls)
[docs]deffilter(self,filter:str,comparison_operation:Union[str,None]=None,value1:Union[Any,None]=None,value2:Union[Any,None]=None)->'XAList':
- """Filters the list by the given parameters.
+ .. versionadded:: 0.0.8
+ """
+ def__init__(self,prompt:str="Choose File",types:list[str]=None,default_location:Union[str,None]=None,show_invisibles:bool=False,multiple_selections_allowed:bool=False,show_package_contents:bool=False):
+ super().__init__()
+ self.prompt:str=prompt#: The prompt to display in the dialog box
+ self.types:list[str]=types#: The file types/type identifiers to allow for selection
+ self.default_location:Union[str,None]=default_location#: The default file location
+ self.show_invisibles:bool=show_invisibles#: Whether invisible files and folders are shown
+ self.multiple_selections_allowed:bool=multiple_selections_allowed#: Whether the user can select multiple files
+ self.show_package_contents:bool=show_package_contents#: Whether to show the contents of packages
- 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.
+
[docs]defdisplay(self)->Union[XAPath,None]:
+ """Displays the file chooser, waits for the user to select a file or cancel, then returns the selected file URL or None if cancelled.
- :param filter: A format string or a property name
- :type filter: str
- :param comparison_operation: The symbol or name of a comparison operation, such as > or <, defaults to None
- :type comparison_operation: Union[str, None], optional
- :param value1: The first value to compare each list item's property value against, defaults to None
- :type value1: Union[Any, None], optional
- :param value2: The second value to compare each list item's property value against, defaults to None
- :type value2: Union[Any, None], optional
- :return: The filter XAList object
- :rtype: XAList
+ :return: The selected file URL or None if no file was selected
+ :rtype: Union[XAPath, None]
- :Example 1: Get the last file sent by you (via this machine) in Messages.app
+ .. versionadded:: 0.0.8
+ """
+ types=[x.replace("'","")forxinself.types]
+ types=str(types).replace("'",'"')
+ types_str="of type "+typesifself.typesisnotNoneelse""
- >>> 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>
+ default_location_str="default location \""+self.default_location+"\""ifself.default_locationisnotNoneelse""
- :Example 2: Get the list of favorite photos/videos from Photos.app
+ script=AppleScript(f"""
+ tell application "Terminal"
+ choose file with prompt \"{self.prompt}\"{types_str}{default_location_str} invisibles {self.show_invisibles} multiple selections allowed {self.multiple_selections_allowed} showing package contents {self.show_package_contents}
+ end tell
+ """)
+ result=script.run()["event"]
- >>> 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', ...]>
+ ifresultisnotNone:
+ ifself.multiple_selections_allowed:
+ values=[]
+ forxinrange(1,result.numberOfItems()+1):
+ desc=result.descriptorAtIndex_(x)
+ values.append(XAPath(desc.fileURLValue()))
+ returnvalues
+ else:
+ returnXAPath(result.fileURLValue())
- .. 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>
- .. versionadded:: 0.0.8
- """
- ifcomparison_operationisnotNoneandvalue1isnotNone:
- predicate=XAPredicate()
- ifcomparison_operationin["=","==","eq","EQ","equals","EQUALS"]:
- predicate.add_eq_condition(filter,value1)
- elifcomparison_operationin["!=","!==","neq","NEQ","not equal to","NOT EQUAL TO"]:
- predicate.add_neq_condition(filter,value1)
- elifcomparison_operationin[">","gt","GT","greater than","GREATER THAN"]:
- predicate.add_gt_condition(filter,value1)
- elifcomparison_operationin["<","lt","LT","less than","LESS THAN"]:
- predicate.add_lt_condition(filter,value1)
- elifcomparison_operationin[">=","geq","GEQ","greater than or equal to","GREATER THAN OR EQUAL TO"]:
- predicate.add_geq_condition(filter,value1)
- elifcomparison_operationin["<=","leq","LEQ","less than or equal to","LESS THAN OR EQUAL TO"]:
- predicate.add_leq_condition(filter,value1)
- elifcomparison_operationin["begins with","beginswith","BEGINS WITH","BEGINSWITH"]:
- predicate.add_begins_with_condition(filter,value1)
- elifcomparison_operationin["contains","CONTAINS"]:
- predicate.add_contains_condition(filter,value1)
- elifcomparison_operationin["ends with","endswith","ENDS WITH","ENDSWITH"]:
- predicate.add_ends_with_condition(filter,value1)
- elifcomparison_operationin["between","BETWEEN"]:
- predicate.add_between_condition(filter,value1,value2)
- elifcomparison_operationin["matches","MATCHES"]:
- predicate.add_match_condition(filter,value1)
+
+ .. versionadded:: 0.0.8
+ """
+ def__init__(self,prompt:str="Choose Folder",default_location:Union[str,None]=None,show_invisibles:bool=False,multiple_selections_allowed:bool=False,show_package_contents:bool=False):
+ super().__init__()
+ self.prompt:str=prompt#: The prompt to display in the dialog box
+ self.default_location:Union[str,None]=default_location#: The default folder location
+ self.show_invisibles:bool=show_invisibles#: Whether invisible files and folders are shown
+ self.multiple_selections_allowed:bool=multiple_selections_allowed#: Whether the user can select multiple folders
+ self.show_package_contents:bool=show_package_contents#: Whether to show the contents of packages
-
[docs]defat(self,index:int)->XAObject:
- """Retrieves the element at the specified index.
+
[docs]defdisplay(self)->Union[XAPath,None]:
+ """Displays the folder chooser, waits for the user to select a folder or cancel, then returns the selected folder URL or None if cancelled.
- :param index: The index of the desired element
- :type index: int
- :return: The PyXA-wrapped element object
- :rtype: XAObject
+ :return: The selected folder URL or None if no folder was selected
+ :rtype: Union[XAPath, None]
- .. versionadded:: 0.0.6
+ .. versionadded:: 0.0.8 """
- returnself._new_element(self.xa_elem[index],self.xa_ocls)
-
[docs]deffirst(self)->XAObject:
- """Retrieves the first element of the list as a wrapped PyXA object.
+ default_location_str="default location \""+self.default_location+"\""ifself.default_locationisnotNoneelse""
- :return: The wrapped object
- :rtype: XAObject
+ script=AppleScript(f"""
+ tell application "Terminal"
+ choose folder with prompt \"{self.prompt}\"{default_location_str} invisibles {self.show_invisibles} multiple selections allowed {self.multiple_selections_allowed} showing package contents {self.show_package_contents}
+ end tell
+ """)
+ result=script.run()["event"]
+ ifresultisnotNone:
+ ifself.multiple_selections_allowed:
+ values=[]
+ forxinrange(1,result.numberOfItems()+1):
+ desc=result.descriptorAtIndex_(x)
+ values.append(XAPath(desc.fileURLValue()))
+ returnvalues
+ else:
+ returnXAPath(result.fileURLValue())
[docs]deflast(self)->XAObject:
- """Retrieves the last element of the list as a wrapped PyXA object.
- :return: The wrapped object
- :rtype: XAObject
- .. versionadded:: 0.0.3
- """
- returnself._new_element(self.xa_elem.lastObject(),self.xa_ocls)
[docs]defshuffle(self)->'XAList':
- """Randomizes the order of objects in the list.
+ .. versionadded:: 0.1.0
+ """
+ def__init__(self,title:Union[str,None]=None,prompt:Union[str,None]=None,multiple_selections_allowed:bool=False):
+ super().__init__()
+ self.title:str=title#: The dialog window title
+ self.prompt:str=prompt#: The prompt to be displayed in the dialog box
+ self.multiple_selections_allowed:bool=multiple_selections_allowed#: Whether to allow multiple items to be selected
- :return: A reference to the shuffled XAList
- :rtype: XAList
+
[docs]defdisplay(self)->str:
+ """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.
- .. versionadded:: 0.0.3
+ :return: The name of the selected application
+ :rtype: str
+
+ .. versionadded:: 0.0.8 """
- self.xa_elem=self.xa_elem.shuffledArray()
- returnself
-
[docs]defpush(self,element:XAObject):
- """Appends the object referenced by the provided PyXA wrapper to the end of the list.
+ script=AppleScript("tell application \"Terminal\"")
+ dialog_str="choose application "
+ ifself.titleisnotNone:
+ dialog_str+=f"with title \"{self.title}\" "
+ ifself.promptisnotNone:
+ dialog_str+=f"with prompt \"{self.prompt}\""
+ dialog_str+=f"multiple selections allowed {self.multiple_selections_allowed} "
+ script.add(dialog_str)
+ script.add("end tell")
- .. versionadded:: 0.0.3
- """
- self.xa_elem.addObject_(element.xa_elem)
+ returnscript.run()["string"]
-
[docs]definsert(self,element:XAObject,index:int):
- """Inserts the object referenced by the provided PyXA wrapper at the specified index.
- .. versionadded:: 0.0.3
- """
- self.xa_elem.insertObject_atIndex_(element.xa_elem,index)
-
[docs]defpop(self,index:int=-1)->XAObject:
- """Removes the object at the specified index from the list and returns it.
- .. versionadded:: 0.0.3
- """
- removed=self.xa_elem.lastObject()
- self.xa_elem.removeLastObject()
- returnself._new_element(removed,self.xa_ocls)
+
[docs]classXAFileNameDialog(XAObject):
+ """A file name input window.
- def__getitem__(self,key:Union[int,slice]):
- ifisinstance(key,slice):
- arr=AppKit.NSMutableArray.alloc().initWithArray_([self.xa_elem[index]forindexinrange(key.start,key.stop,key.stepor1)])
- returnself._new_element(arr,self.__class__)
- returnself._new_element(self.xa_elem[key],self.xa_ocls)
+ .. versionadded:: 0.0.8
+ """
+ def__init__(self,prompt:str="Specify file name and location",default_name:str="New File",default_location:Union[str,None]=None):
+ super().__init__()
+ self.prompt:str=prompt#: The prompt to display in the dialog box
+ self.default_name:str=default_name#: The default name for the new file
+ self.default_location:Union[str,None]=default_location#: The default file location
- def__len__(self):
- ifhasattr(self.xa_elem,"count"):
- returnself.xa_elem.count()
- returnlen(self.xa_elem)
+
[docs]defdisplay(self)->Union[XAPath,None]:
+ """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.
- def__reversed__(self):
- self.xa_elem=self.xa_elem.reverseObjectEnumerator().allObjects()
- returnself
+ :return: The specified file URL or None if no file name was inputted
+ :rtype: Union[XAPath, None]
- def__iter__(self):
- return(self._new_element(object,self.xa_ocls)forobjectinself.xa_elem.objectEnumerator())
+ .. versionadded:: 0.0.8
+ """
- def__repr__(self):
- return"<"+str(type(self))+str(self.xa_elem)+">"
+ default_location_str="default location \""+self.default_location+"\""ifself.default_locationisnotNoneelse""
+
+ script=AppleScript(f"""
+ tell application "Terminal"
+ choose file name with prompt \"{self.prompt}\" default name \"{self.default_name}\"{default_location_str}
+ end tell
+ """)
+ result=script.run()["event"]
+ ifresultisnotNone:
+ returnXAPath(result.fileURLValue())
[docs]classXAMenuBar(XAObject):
+ def__init__(self):
+ """Creates a new menu bar object for interacting with the system menu bar.
- self.front_window:XAWindow#: The front window of the application process
+ .. versionadded:: 0.0.9
+ """
+ self._menus={}
+ self._menu_items={}
+ self._methods={}
- @property
- deffront_window(self)->'XAWindow':
- returnself._new_element(self.xa_elem.windows()[0],XAWindow)
+ detector=self
+ classMyApplicationAppDelegate(AppKit.NSObject):
+ start_time=datetime.now()
-
[docs]defadd_menu(self,title:str,image:Union['XAImage',None]=None,tool_tip:Union[str,None]=None,img_width:int=30,img_height:int=30):
+ """Adds a new menu to be displayed in the system menu bar.
-
[docs]classXAApplication(XAObject,XAClipboardCodable):
- """A general application class for both officially scriptable and non-scriptable applications.
+ :param title: The name of the menu
+ :type title: str
+ :param image: The image to display for the menu, defaults to None
+ :type image: Union[XAImage, None], optional
+ :param tool_tip: The tooltip to display on hovering over the menu, defaults to None
+ :type tool_tip: Union[str, None], optional
+ :param img_width: The width of the image, in pixels, defaults to 30
+ :type img_width: int, optional
+ :param img_height: The height of the image, in pixels, defaults to 30
+ :type img_height: int, optional
- .. seealso:: :class:`XASBApplication`, :class:`XAWindow`
+ :Example:
- .. versionadded:: 0.0.1
- """
- def__init__(self,properties):
- super().__init__(properties)
- self.xa_wcls=XAWindow
+ >>> import PyXA
+ >>> menu_bar = PyXA.XAMenuBar()
+ >>> img = PyXA.XAImage("/Users/steven/Downloads/Blackness.jpg")
+ >>> menu_bar.add_menu("Menu 1", image=img, img_width=100, img_height=100)
+ >>> menu_bar.display()
- predicate=AppKit.NSPredicate.predicateWithFormat_("displayedName == %@",self.xa_elem.localizedName())
- process=self.xa_sevt.processes().filteredArrayUsingPredicate_(predicate)[0]
+ .. versionadded:: 0.0.9
+ """
+ status_bar=AppKit.NSStatusBar.systemStatusBar()
+ status_item=status_bar.statusItemWithLength_(AppKit.NSVariableStatusItemLength).retain()
+ status_item.setTitle_(title)
+
+ ifisinstance(image,XAImage):
+ img=image.xa_elem.copy()
+ img.setScalesWhenResized_(True)
+ img.setSize_((img_width,img_height))
+ status_item.button().setImage_(img)
- properties={
- "parent":self,
- "appspace":self.xa_apsp,
- "workspace":self.xa_wksp,
- "element":process,
- "appref":self.xa_aref,
- "system_events":self.xa_sevt,
- "window_class":self.xa_wcls
- }
- self.xa_prcs=XAProcess(properties)
+ status_item.setHighlightMode_(objc.YES)
- self.bundle_identifier:str#: The bundle identifier for the application
- self.bundle_url:str#: The file URL of the application bundle
- self.executable_url:str#: The file URL of the application's executable
- self.frontmost:bool#: Whether the application is the active application
- self.launch_date:datetime#: The date and time that the application was launched
- self.localized_name:str#: The application's name
- self.owns_menu_bar:bool#: Whether the application owns the top menu bar
- self.process_identifier:str#: The process identifier for the application instance
+ ifisinstance(tool_tip,str):
+ status_item.setToolTip_(tool_tip)
- @property
- defbundle_identifier(self)->str:
- returnself.xa_elem.bundleIdentifier()
+ menu=AppKit.NSMenu.alloc().init()
+ status_item.setMenu_(menu)
- @property
- defbundle_url(self)->str:
- returnself.xa_elem.bundleURL()
+ status_item.setEnabled_(objc.YES)
+ self._menus[title]=status_item
[docs]defset_image(self,item_name:str,image:'XAImage',img_width:int=30,img_height:int=30):
+ """Sets the image displayed for a menu or menu item.
- @property
- defprocess_identifier(self)->str:
- returnself.xa_elem.processIdentifier()
+ :param item_name: The name of the item to update
+ :type item_name: str
+ :param image: The image to display
+ :type image: XAImage
+ :param img_width: The width of the image, in pixels, defaults to 30
+ :type img_width: int, optional
+ :param img_height: The height of the image, in pixels, defaults to 30
+ :type img_height: int, optional
-
[docs]defactivate(self)->'XAApplication':
- """Activates the application, bringing its window(s) to the front and launching the application beforehand if necessary.
+ :Example: Set Image on State Change
- :return: A reference to the PyXA application object.
- :rtype: XAApplication
+ >>> import PyXA
+ >>> current_state = True # On
+ >>> img_on = PyXA.XAImage("/Users/exampleUser/Documents/on.jpg")
+ >>> img_off = PyXA.XAImage("/Users/exampleUser/Documents/off.jpg")
+ >>> menu_bar = PyXA.XAMenuBar()
+ >>> menu_bar.add_menu("Status", image=img_on)
+ >>>
+ >>> def update_state():
+ >>> global current_state
+ >>> if current_state is True:
+ >>> # ... (Actions for turning off)
+ >>> menu_bar.set_text("Turn off", "Turn on")
+ >>> menu_bar.set_image("Status", img_off)
+ >>> current_state = False
+ >>> else:
+ >>> # ... (Actions for turning on)
+ >>> menu_bar.set_text("Turn off", "Turn off")
+ >>> menu_bar.set_image("Status", img_on)
+ >>> current_state = True
- .. seealso:: :func:`terminate`, :func:`unhide`, :func:`focus`
+ menu_bar.add_item("Status", "Turn off", update_state)
+ menu_bar.display()
- .. versionadded:: 0.0.1
+ .. versionadded:: 0.0.9 """
- self.xa_elem.activateWithOptions_(AppKit.NSApplicationActivateIgnoringOtherApps)
- returnself
[docs]defhide(self)->'XAApplication':
- """Hides all windows of the application.
- :return: A reference to the PyXA application object.
- :rtype: XAApplication
- :Example:
- >>> import PyXA
- >>> safari = PyXA.application("Safari")
- >>> safari.hide()
+#############################
+### System / Image Events ###
+#############################
+# ? Move into separate XAFileSystemBase.py file?
+
[docs]classXAEventsApplication(XACanOpenPath):
+ """A base class for the System and Image events applications.
- .. seealso:: :func:`unhide`
+ .. versionadded:: 0.1.0
+ """
+
[docs]classXADiskItemList(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.
+
+ .. versionadded:: 0.1.0
+ """
+ def__init__(self,properties:dict,filter:Union[dict,None]=None,object_class=None):
+ ifobject_classisNone:
+ object_class=XADiskItem
+ super().__init__(properties,object_class,filter)
- .. versionadded:: 0.0.1
+
[docs]defbusy_status(self)->list['bool']:
+ """Retrieves the busy status of each disk item in the list.
+
+ .. versionadded:: 0.1.0 """
- self.xa_elem.hide()
- returnself
[docs]defunhide(self)->'XAApplication':
- """Unhides (reveals) all windows of the application, but does not does not activate them.
+
[docs]defcontainer(self)->'XADiskItemList':
+ """Retrieves the containing folder or disk of each disk item in the list.
- :return: A reference to the PyXA application object.
- :rtype: XAApplication
+ .. versionadded:: 0.1.0
+ """
+ ls=self.xa_elem.arrayByApplyingSelector_("container")
+ returnself._new_element(ls,XADiskItemList)
- :Example:
+
[docs]defcreation_date(self)->list['datetime']:
+ """Retrieves the creation date of each disk item in the list.
- >>> import PyXA
- >>> safari = PyXA.application("Safari")
- >>> safari.unhide()
+ .. versionadded:: 0.1.0
+ """
+ returnlist(self.xa_elem.arrayByApplyingSelector_("creationDate"))
- .. seealso:: :func:`hide`
+
[docs]defdisplayed_name(self)->list['str']:
+ """Retrieves the displayed name of each disk item in the list.
- .. versionadded:: 0.0.1
+ .. versionadded:: 0.1.0 """
- self.xa_elem.unhide()
- returnself
[docs]deffocus(self)->'XAApplication':
- """Hides the windows of all applications except this one.
+
[docs]defid(self)->list['str']:
+ """Retrieves the unique ID of each disk item in the list.
- :return: A reference to the PyXA application object.
- :rtype: XAApplication
+ .. versionadded:: 0.1.0
+ """
+ returnlist(self.xa_elem.arrayByApplyingSelector_("id"))
- :Example:
+
[docs]defmodification_date(self)->list['datetime']:
+ """Retrieves the last modified date of each disk item in the list.
- >>> import PyXA
- >>> safari = PyXA.application("Safari")
- >>> safari.focus()
+ .. versionadded:: 0.1.0
+ """
+ returnlist(self.xa_elem.arrayByApplyingSelector_("modificationDate"))
- .. seealso:: :func:`unfocus`
+
[docs]defname(self)->list['str']:
+ """Retrieves the name of each disk item in the list.
- .. versionadded:: 0.0.1
+ .. versionadded:: 0.1.0 """
- forappinself.xa_wksp.runningApplications():
- ifapp.localizedName()!=self.xa_elem.localizedName():
- app.hide()
- else:
- app.unhide()
- returnself
[docs]defunfocus(self)->'XAApplication':
- """Unhides (reveals) the windows of all other applications, but does not activate them.
+
[docs]defname_extension(self)->list['str']:
+ """Retrieves the name extension of each disk item in the list.
- :return: A reference to the PyXA application object.
- :rtype: XAApplication
+ .. versionadded:: 0.1.0
+ """
+ returnlist(self.xa_elem.arrayByApplyingSelector_("nameExtension"))
- :Example:
+
[docs]defpackage_folder(self)->list['bool']:
+ """Retrieves the package folder status of each disk item in the list.
- >>> import PyXA
- >>> safari = PyXA.application("Safari")
- >>> safari.unfocus()
+ .. versionadded:: 0.1.0
+ """
+ returnlist(self.xa_elem.arrayByApplyingSelector_("packageFolder"))
- .. seealso:: :func:`focus`
+
[docs]defpath(self)->list['XAPath']:
+ """Retrieves the file system path of each disk item in the list.
- .. versionadded:: 0.0.1
+ .. versionadded:: 0.1.0 """
- forappinself.xa_wksp.runningApplications():
- app.unhide()
- returnself
[docs]defphysical_size(self)->list['int']:
+ """Retrieves the actual disk space used by each disk item in the list.
- @property
- deffront_window(self)->'XAWindow':
- returnself.xa_prcs.front_window
+ .. versionadded:: 0.1.0
+ """
+ returnlist(self.xa_elem.arrayByApplyingSelector_("physicalSize"))
[docs]defposix_path(self)->list[XAPath]:
+ """Retrieves the POSIX file system path of each disk item in the list.
-
[docs]defget_clipboard_representation(self)->List[Union[str,AppKit.NSURL,AppKit.NSImage]]:
- """Gets a clipboard-codable representation of the application.
+ .. versionadded:: 0.1.0
+ """
+ ls=self.xa_elem.arrayByApplyingSelector_("POSIXPath")
+ return[XAPath(x)forxinls]
- 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
+
[docs]defsize(self)->list['int']:
+ """Retrieves the logical size of each disk item in the list.
- 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 different for other applications.
+ .. versionadded:: 0.1.0
+ """
+ returnlist(self.xa_elem.arrayByApplyingSelector_("size"))
[docs]defurl(self)->list['XAURL']:
+ """Retrieves the URL of each disk item in the list.
- .. versionadded:: 0.0.8
+ .. versionadded:: 0.1.0 """
- return[self.xa_elem.localizedName(),self.xa_elem.bundleURL(),self.xa_elem.icon()]
[docs]defvisible(self)->list['bool']:
+ """Retrieves the visible status of each item in the list.
+ .. versionadded:: 0.1.0
+ """
+ returnlist(self.xa_elem.arrayByApplyingSelector_("visible"))
-
[docs]classXASound(XAObject,XAClipboardCodable):
- """A wrapper class for NSSound objects and associated methods.
+
[docs]defvolume(self)->list['str']:
+ """Retrieves the volume on which each item in the list resides.
- .. versionadded:: 0.0.1
- """
- def__init__(self,sound_file:Union[str,AppKit.NSURL]):
- ifisinstance(sound_file,str):
- if"/"insound_file:
- sound_file=XAPath(sound_file)
- else:
- sound_file=XAPath("/System/Library/Sounds/"+sound_file+".aiff")
- self.file=sound_file
- self.xa_elem=AppKit.NSSound.alloc()
- self.xa_elem.initWithContentsOfURL_byReference_(sound_file.xa_elem,True)
+ .. versionadded:: 0.1.0
+ """
+ returnlist(self.xa_elem.arrayByApplyingSelector_("volume"))
-
[docs]defplay(self)->'XASound':
- """Plays the sound from the beginning.
+
[docs]defby_busy_status(self,busy_status:bool)->'XADiskItem':
+ """Retrieves item whose busy status matches the given boolean value.
- :return: A reference to this sound object.
- :rtype: XASound
+ .. versionadded:: 0.1.0
+ """
+ returnself.by_property("busyStatus",busy_status)
[docs]defpause(self)->'XASound':
- """Pauses the sound.
+
[docs]defby_displayed_name(self,displayed_name:str)->'XADiskItem':
+ """Retrieves item whose displayed name matches the given name.
- :return: A reference to this sound object.
- :rtype: XASound
+ .. versionadded:: 0.1.0
+ """
+ returnself.by_property("displayedName",displayed_name)
- :Example:
+
[docs]defby_id(self,id:str)->'XADiskItem':
+ """Retrieves item whose ID matches the given ID.
- >>> import PyXA
- >>> glass_sound = PyXA.sound("Glass")
- >>> glass_sound.pause()
+ .. versionadded:: 0.1.0
+ """
+ returnself.by_property("id",id)
- .. seealso:: :func:`resume`, :func:`stop`
+
[docs]defby_modification_date(self,modification_date:datetime)->'XADiskItem':
+ """Retrieves item whose date matches the given date.
- .. versionadded:: 0.0.1
+ .. versionadded:: 0.1.0 """
- self.xa_elem.pause()
- returnself
[docs]defresume(self)->'XASound':
- """Plays the sound starting from the time it was last paused at.
+
[docs]defby_name(self,name:str)->'XADiskItem':
+ """Retrieves item whose name matches the given name.
- :return: A reference to this sound object.
- :rtype: XASound
+ .. versionadded:: 0.1.0
+ """
+ returnself.by_property("name",name)
[docs]defset_volume(self,volume:int)->'XASound':
- """Sets the volume of the sound.
+
[docs]defby_size(self,size:int)->'XADiskItem':
+ """Retrieves item whose size matches the given size.
- :param volume: The desired volume of the sound in the range [0.0, 1.0].
- :type volume: int
- :return: A reference to this sound object.
- :rtype: XASound
+ .. versionadded:: 0.1.0
+ """
+ returnself.by_property("size",size)
[docs]defby_visible(self,visible:bool)->'XADiskItem':
+ """Retrieves the item whose visible status matches the given boolean value.
- .. versionadded:: 0.0.1
+ .. versionadded:: 0.1.0 """
- self.xa_elem.setVolume_(volume)
- returnself
+ returnself.by_property("visible",visible)
-
[docs]defvolume(self)->float:
- """Returns the current volume of the sound.
+
[docs]defby_volume(self,volume:str)->'XADiskItem':
+ """Retrieves the item whose volume matches the given volume.
- :return: The volume level of the sound.
- :rtype: int
+ .. versionadded:: 0.1.0
+ """
+ returnself.by_property("volume",volume)
[docs]classXADiskItem(XAObject,XAPathLike):
+ """An item stored in the file system.
- .. seealso:: :func:`set_volume`
+ .. versionadded:: 0.1.0
+ """
+ def__init__(self,properties):
+ super().__init__(properties)
- .. versionadded:: 0.0.1
+ @property
+ defbusy_status(self)->'bool':
+ """Whether the disk item is busy.
+
+ .. versionadded:: 0.1.0 """
- returnself.xa_elem.volume()
+ returnself.xa_elem.busyStatus()
-
[docs]defloop(self,times:int)->'XASound':
- """Plays the sound the specified number of times.
+ @property
+ defcontainer(self)->'XADiskItem':
+ """The folder or disk which has this disk item as an element.
- :param times: The number of times to loop the sound.
- :type times: int
- :return: A reference to this sound object.
- :rtype: XASound
+ .. versionadded:: 0.1.0
+ """
+ returnself._new_element(self.xa_elem.container(),XADiskItem)
- :Example:
+ @property
+ defcreation_date(self)->'datetime':
+ """The date on which the disk item was created.
- >>> import PyXA
- >>> glass_sound = PyXA.sound("Glass")
- >>> glass_sound.loop(10)
+ .. versionadded:: 0.1.0
+ """
+ returnself.xa_elem.creationDate()
- .. versionadded:: 0.0.1
+ @property
+ defdisplayed_name(self)->'str':
+ """The name of the disk item as displayed in the User Interface.
+
+ .. versionadded:: 0.1.0 """
- self.xa_elem.setLoops_(times)
- self.xa_elem.play()
- time.sleep(self.xa_elem.duration()*times)
- self.xa_elem.stop()
- self.xa_elem.setLoops_(0)
- returnself
+ returnself.xa_elem.displayedName()
-
[docs]defget_clipboard_representation(self)->List[Union[AppKit.NSSound,AppKit.NSURL,str]]:
- """Gets a clipboard-codable representation of the sound.
+ @property
+ defid(self)->'str':
+ """The unique ID of the disk item.
- When the clipboard content is set to a sound, the raw sound data, the associated file URL, and the path string of the file are added to the clipboard.
+ .. versionadded:: 0.1.0
+ """
+ returnself.xa_elem.id()
- :return: The clipboard-codable form of the sound
- :rtype: Any
+ @property
+ defmodification_date(self)->'datetime':
+ """The date on which the disk item was last modified.
- .. versionadded:: 0.0.8
+ .. versionadded:: 0.1.0 """
- return[self.xa_elem,self.file.xa_elem,self.file.xa_elem.path()]
+ returnself.xa_elem.modificationDate()
+ @property
+ defname(self)->'str':
+ """The name of the disk item.
+ .. versionadded:: 0.1.0
+ """
+ returnself.xa_elem.name()
+ @property
+ defname_extension(self)->'str':
+ """The extension portion of the name.
-
[docs]classXACommandDetector(XAObject):
- """A command-based query detector.
+ .. versionadded:: 0.1.0
+ """
+ returnself.xa_elem.nameExtension()
- .. versionadded:: 0.0.9
- """
- def__init__(self,command_function_map:Union[Dict[str,Callable[[],Any]],None]=None):
- """Creates a command detector object.
+ @property
+ defpackage_folder(self)->'bool':
+ """Whether the disk item is a package.
- :param command_function_map: A dictionary mapping command strings to function objects
- :type command_function_map: Dict[str, Callable[[], Any]]
+ .. versionadded:: 0.1.0
+ """
+ returnself.xa_elem.packageFolder()
- .. versionadded:: 0.0.9
+ @property
+ defpath(self)->'XAPath':
+ """The file system path of the disk item.
+
+ .. versionadded:: 0.1.0 """
- self.command_function_map=command_function_mapor{}#: The dictionary of commands and corresponding functions to run upon detection
+ returnXAPath(self.xa_elem.path())
-
[docs]defon_detect(self,command:str,function:Callable[[],Any]):
- """Adds or replaces a command to listen for upon calling :func:`listen`, and associates the given function with that command.
+ @property
+ defphysical_size(self)->'int':
+ """The actual space used by the disk item on disk.
- :param command: The command to listen for
- :type command: str
- :param function: The function to call when the command is heard
- :type function: Callable[[], Any]
+ .. versionadded:: 0.1.0
+ """
+ returnself.xa_elem.physicalSize()
- :Example:
+ @property
+ defposix_path(self)->XAPath:
+ """The POSIX file system path of the disk item.
- >>> detector = PyXA.XACommandDetector()
- >>> detector.on_detect("go to google", PyXA.XAURL("http://google.com").open)
- >>> detector.listen()
+ .. versionadded:: 0.1.0
+ """
+ returnXAPath(self.xa_elem.POSIXPath())
- .. versionadded:: 0.0.9
+ @property
+ defsize(self)->'int':
+ """The logical size of the disk item.
+
+ .. versionadded:: 0.1.0 """
- self.command_function_map[command]=function
+ returnself.xa_elem.size()
-
[docs]deflisten(self)->Any:
- """Begins listening for the specified commands.
+ @property
+ defurl(self)->'XAURL':
+ """The URL of the disk item.
- :return: The execution return value of the corresponding command function
- :rtype: Any
+ .. versionadded:: 0.1.0
+ """
+ returnXAURL(self.xa_elem.URL())
- :Example:
+ @property
+ defvisible(self)->'bool':
+ """Whether the disk item is visible.
- >>> import PyXA
- >>> PyXA.speak("What app do you want to open?")
- >>> PyXA.XACommandDetector({
- >>> "safari": PyXA.application("Safari").activate,
- >>> "messages": PyXA.application("Messages").activate,
- >>> "shortcuts": PyXA.application("Shortcuts").activate,
- >>> "mail": PyXA.application("Mail").activate,
- >>> "calendar": PyXA.application("Calendar").activate,
- >>> "notes": PyXA.application("Notes").activate,
- >>> "music": PyXA.application("Music").activate,
- >>> "tv": PyXA.application("TV").activate,
- >>> "pages": PyXA.application("Pages").activate,
- >>> "numbers": PyXA.application("Numbers").activate,
- >>> "keynote": PyXA.application("Keynote").activate,
- >>> }).listen()
+ .. versionadded:: 0.1.0
+ """
+ returnself.xa_elem.visible()
- .. versionadded:: 0.0.9
+ @property
+ defvolume(self)->'str':
+ """The volume on which the disk item resides.
+
+ .. versionadded:: 0.1.0 """
- command_function_map=self.command_function_map
- return_value=None
- classNSSpeechRecognizerDelegate(AppKit.NSObject):
- defspeechRecognizer_didRecognizeCommand_(self,recognizer,cmd):
- return_value=command_function_map[cmd]()
- AppHelper.stopEventLoop()
+ returnself.xa_elem.volume()
- recognizer=AppKit.NSSpeechRecognizer.alloc().init()
- recognizer.setCommands_(list(command_function_map.keys()))
- recognizer.setBlocksOtherRecognizers_(True)
- recognizer.setDelegate_(NSSpeechRecognizerDelegate.alloc().init().retain())
- recognizer.startListening()
- AppHelper.runConsoleEventLoop()
+
[docs]classXAAliasList(XADiskItemList):
+ """A wrapper around lists of aliases that employs fast enumeration techniques.
- .. versionadded:: 0.0.9
- """
- def__init__(self,finish_conditions:Union[None,Dict[Callable[[str],bool],Callable[[str],bool]]]=None):
- """Creates a speech recognizer object.
+ All properties of aliases can be called as methods on the wrapped list, returning a list containing each alias' value for the property.
- By default, with no other rules specified, the Speech Recognizer will timeout after 10 seconds once :func:`listen` is called.
+ .. versionadded:: 0.1.0
+ """
+ def__init__(self,properties:dict,filter:Union[dict,None]=None):
+ super().__init__(properties,filter,XAAlias)
- :param finish_conditions: A dictionary of rules and associated methods to call when a rule evaluates to true, defaults to None
- :type finish_conditions: Union[None, Dict[Callable[[str], bool], Callable[[str], bool]]], optional
+
[docs]defcreator_type(self)->list['str']:
+ """Retrieves the OSType identifying the application that created each alias in the list
- .. versionadded:: 0.0.9
+ .. versionadded:: 0.1.0 """
- default_conditions={
- lambdax:self.time_elapsed>timedelta(seconds=10):lambdax:self.spoken_query,
- }
- self.finish_conditions:Callable[[str],bool]=finish_conditionsordefault_conditions#: A dictionary of rules and associated methods to call when a rule evaluates to true
- self.spoken_query:str=""#: The recognized spoken input
- self.start_time:datetime#: The time that the Speech Recognizer begins listening
- self.time_elapsed:timedelta#: The amount of time passed since the start time
+ returnlist(self.xa_elem.arrayByApplyingSelector_("creatorType"))
- def__prepare(self):
- # Request microphone access if we don't already have it
- Speech.SFSpeechRecognizer.requestAuthorization_(None)
+
[docs]defdefault_application(self)->'XADiskItemList':
+ """Retrieves the applications that will launch if each alias in the list is opened.
- # Set up audio session
- self.audio_session=AVFoundation.AVAudioSession.sharedInstance()
- self.audio_session.setCategory_mode_options_error_(AVFoundation.AVAudioSessionCategoryRecord,AVFoundation.AVAudioSessionModeMeasurement,AVFoundation.AVAudioSessionCategoryOptionDuckOthers,None)
- self.audio_session.setActive_withOptions_error_(True,AVFoundation.AVAudioSessionSetActiveOptionNotifyOthersOnDeactivation,None)
+ .. versionadded:: 0.1.0
+ """
+ ls=self.xa_elem.arrayByApplyingSelector_("defaultApplication")
+ returnself._new_element(ls,XADiskItemList)
- # Set up recognition request
- self.recognizer=Speech.SFSpeechRecognizer.alloc().init()
- self.recognition_request=Speech.SFSpeechAudioBufferRecognitionRequest.alloc().init()
- self.recognition_request.setShouldReportPartialResults_(True)
+
[docs]deffile_type(self)->list['str']:
+ """Retrieves the OSType identifying the type of data contained in each alias in the list.
- # Set up audio engine
- self.audio_engine=AVFoundation.AVAudioEngine.alloc().init()
- self.input_node=self.audio_engine.inputNode()
- recording_format=self.input_node.outputFormatForBus_(0)
- self.input_node.installTapOnBus_bufferSize_format_block_(0,1024,recording_format,
- lambdabuffer,_when:self.recognition_request.appendAudioPCMBuffer_(buffer))
- self.audio_engine.prepare()
- self.audio_engine.startAndReturnError_(None)
+ .. versionadded:: 0.1.0
+ """
+ returnlist(self.xa_elem.arrayByApplyingSelector_("fileType"))
-
[docs]defon_detect(self,rule:Callable[[str],bool],method:Callable[[str],bool]):
- """Sets the given rule to call the specified method if a spoken query passes the rule.
+
[docs]defkind(self)->list['str']:
+ """Retrieves the kind of each alias in the list.
- :param rule: A function that takes the spoken query as a parameter and returns a boolean value depending on whether the query passes a desired rule
- :type rule: Callable[[str], bool]
- :param method: A function that takes the spoken query as a parameter and acts on it
- :type method: Callable[[str], bool]
+ .. versionadded:: 0.1.0
+ """
+ returnlist(self.xa_elem.arrayByApplyingSelector_("kind"))
- .. versionadded:: 0.0.9
+
[docs]defproduct_version(self)->list['str']:
+ """Retrieves the product version of each alias in the list.
+
+ .. versionadded:: 0.1.0 """
- self.finish_conditions[rule]=method
[docs]deflisten(self)->Any:
- """Begins listening for a query until a rule returns True.
+
[docs]defshort_version(self)->list['str']:
+ """Retrieves the short version of the application bundle referenced by each alias in the list.
- :return: The value returned by the method invoked upon matching some rule
- :rtype: Any
+ .. versionadded:: 0.1.0
+ """
+ returnlist(self.xa_elem.arrayByApplyingSelector_("shortVersion"))
- .. versionadded:: 0.0.9
+
[docs]defstationery(self)->list['bool']:
+ """Retrieves the stationery status of each alias in the list.
+
+ .. versionadded:: 0.1.0 """
- self.start_time=datetime.now()
- self.time_elapsed=None
- self.__prepare()
+ returnlist(self.xa_elem.arrayByApplyingSelector_("stationery"))
[docs]deftype_identifier(self)->list['str']:
+ """Retrieves the type identifier of each alias in the list.
- recognition_task=self.recognizer.recognitionTaskWithRequest_resultHandler_(self.recognition_request,detect_speech)
- whileself.spoken_query==""ornotany(x(self.spoken_query)forxinself.finish_conditions):
- self.time_elapsed=datetime.now()-self.start_time
- AppKit.NSRunLoop.currentRunLoop().runUntilDate_(datetime.now()+timedelta(seconds=0.5))
+ .. versionadded:: 0.1.0
+ """
+ returnlist(self.xa_elem.arrayByApplyingSelector_("typeIdentifier"))
[docs]defversion(self)->list['str']:
+ """Retrieves the version of the application bundle referenced by each alias in the list.
+ .. versionadded:: 0.1.0
+ """
+ returnlist(self.xa_elem.arrayByApplyingSelector_("version"))
+
[docs]defby_creator_type(self,creator_type:str)->'XAAlias':
+ """Retrieves the alias whose creator type matches the given creator type.
+ .. versionadded:: 0.1.0
+ """
+ returnself.by_property("creatorType",creator_type)
-
[docs]classXASpotlight(XAObject):
- """A Spotlight query for files on the disk.
+
[docs]defby_default_application(self,default_application:'XADiskItem')->'XAAlias':
+ """Retrieves the alias whose default application matches the given application.
- .. versionadded:: 0.0.9
- """
- def__init__(self,*query:List[Any]):
- self.query:List[Any]=query#: The query terms to search
- self.timeout:int=10#: The amount of time in seconds to timeout the search after
- self.predicate:Union[str,XAPredicate]=None#: The predicate to filter search results by
- self.results:List[XAPath]#: The results of the search
- self.__results=None
+ .. versionadded:: 0.1.0
+ """
+ returnself.by_property("defaultApplication",default_application.xa_elem)
[docs]defby_short_version(self,short_version:str)->'XAAlias':
+ """Retrieves the alias whose short version matches the given text.
-
[docs]defshow_in_finder(self):
- """Shows the search in Finder. This might not reveal the same search results.
+ .. versionadded:: 0.1.0
+ """
+ returnself.by_property("shortVersion",short_version)
- .. versionadded:: 0.0.9
+
[docs]defby_stationery(self,stationery:bool)->'XAAlias':
+ """Retrieves the alias whose stationery status matches the given boolean value.
+
+ .. versionadded:: 0.1.0 """
- AppKit.NSWorkspace.sharedWorkspace().showSearchResultsForQueryString_(str(self.query))
+ returnself.by_property("stationery",stationery)
- def__search_by_strs(self,terms:Tuple[str]):
- expanded_terms=[[x]*3forxinterms]
- expanded_terms=[xforsublistinexpanded_termsforxinsublist]
- format="((kMDItemDisplayName CONTAINS %@) OR (kMDItemTextContent CONTAINS %@) OR (kMDItemFSName CONTAINS %@)) AND "*len(terms)
- self.__search_with_predicate(format[:-5],*expanded_terms)
+
[docs]defby_type_identifier(self,type_identifier:str)->'XAAlias':
+ """Retrieves the alias whose type identifier matches the given type identifier.
- def__search_by_date(self,date:datetime):
- self.__search_with_predicate(f"((kMDItemContentCreationDate > %@) AND (kMDItemContentCreationDate < %@)) OR ((kMDItemContentModificationDate > %@) AND (kMDItemContentModificationDate < %@)) OR ((kMDItemFSCreationDate > %@) AND (kMDItemFSCreationDate < %@)) OR ((kMDItemFSContentChangeDate > %@) AND (kMDItemFSContentChangeDate < %@)) OR ((kMDItemDateAdded > %@) AND (kMDItemDateAdded < %@))",*[date-timedelta(hours=12),date+timedelta(hours=12)]*5)
+ .. versionadded:: 0.1.0
+ """
+ returnself.by_property("typeIdentifier",type_identifier)
- def__search_by_date_range(self,date1:datetime,date2:datetime):
- self.__search_with_predicate(f"((kMDItemContentCreationDate > %@) AND (kMDItemContentCreationDate < %@)) OR ((kMDItemContentModificationDate > %@) AND (kMDItemContentModificationDate < %@)) OR ((kMDItemFSCreationDate > %@) AND (kMDItemFSCreationDate < %@)) OR ((kMDItemFSContentChangeDate > %@) AND (kMDItemFSContentChangeDate < %@)) OR ((kMDItemDateAdded > %@) AND (kMDItemDateAdded < %@))",*[date1,date2]*5)
+
[docs]defby_version(self,version:str)->'XAAlias':
+ """Retrieves the alias whose version matches the given version.
- def__search_by_date_strings(self,date:datetime,terms:Tuple[str]):
- expanded_terms=[[x]*3forxinterms]
- expanded_terms=[xforsublistinexpanded_termsforxinsublist]
- format="((kMDItemDisplayName CONTAINS %@) OR (kMDItemTextContent CONTAINS %@) OR (kMDItemFSName CONTAINS %@)) AND "*len(terms)
- format+="(((kMDItemContentCreationDate > %@) AND (kMDItemContentCreationDate < %@)) OR ((kMDItemContentModificationDate > %@) AND (kMDItemContentModificationDate < %@)) OR ((kMDItemFSCreationDate > %@) AND (kMDItemFSCreationDate < %@)) OR ((kMDItemFSContentChangeDate > %@) AND (kMDItemFSContentChangeDate < %@)) OR ((kMDItemDateAdded > %@) AND (kMDItemDateAdded < %@)))"
- self.__search_with_predicate(format,*expanded_terms,*[date-timedelta(hours=12),date+timedelta(hours=12)]*5)
+ .. versionadded:: 0.1.0
+ """
+ returnself.by_property("version",version)
- def__search_by_date_range_strings(self,date1:datetime,date2:datetime,terms:Tuple[str]):
- expanded_terms=[[x]*3forxinterms]
- expanded_terms=[xforsublistinexpanded_termsforxinsublist]
- format="((kMDItemDisplayName CONTAINS %@) OR (kMDItemTextContent CONTAINS %@) OR (kMDItemFSName CONTAINS %@)) AND "*len(terms)
- format+="(((kMDItemContentCreationDate > %@) AND (kMDItemContentCreationDate < %@)) OR ((kMDItemContentModificationDate > %@) AND (kMDItemContentModificationDate < %@)) OR ((kMDItemFSCreationDate > %@) AND (kMDItemFSCreationDate < %@)) OR ((kMDItemFSContentChangeDate > %@) AND (kMDItemFSContentChangeDate < %@)) OR ((kMDItemDateAdded > %@) AND (kMDItemDateAdded < %@)))"
- self.__search_with_predicate(format,*expanded_terms,*[date1,date2]*5)
+
+ @property
+ defcreator_type(self)->'str':
+ """The OSType identifying the application that created the alias.
+ .. versionadded:: 0.1.0
+ """
+ returnself.xa_elem.creatorType()
+ @property
+ defdefault_application(self)->'XADiskItem':
+ """The application that will launch if the alias is opened.
+ .. versionadded:: 0.1.0
+ """
+ returnself._new_element(self.xa_elem.defaultApplication(),XADiskItem)
-
[docs]classXAURL(XAObject,XAClipboardCodable):
- """A URL using any scheme recognized by the system. This can be a file URL.
+ @property
+ deffile_type(self)->'str':
+ """The OSType identifying the type of data contained in the alias.
- .. versionadded:: 0.0.5
- """
- def__init__(self,url:Union[str,AppKit.NSURL]):
- super().__init__()
- self.parameters:str#: The query parameters of the URL
- self.scheme:str#: The URI scheme of the URL
- self.fragment:str#: The fragment identifier following a # symbol in the URL
- self.port:int#: The port that the URL points to
- self.html:element.tag#: The html of the URL
- self.title:str#: The title of the URL
- self.soup:BeautifulSoup=None#: The bs4 object for the URL, starts as None until a bs4-related action is made
- self.url:str=url#: The string form of the URL
- ifisinstance(url,str):
- url=url.replace(" ","%20")
- url=AppKit.NSURL.alloc().initWithString_(url)
- self.xa_elem=url
+ .. versionadded:: 0.1.0
+ """
+ returnself.xa_elem.fileType()@property
- defbase_url(self)->str:
- returnself.xa_elem.host()
+ defkind(self)->'str':
+ """The kind of alias, as shown in Finder.
+
+ .. versionadded:: 0.1.0
+ """
+ returnself.xa_elem.kind()@property
- defparameters(self)->str:
- returnself.xa_elem.query()
+ defproduct_version(self)->'str':
+ """The version of the product (visible at the top of the "Get Info" window).
+
+ .. versionadded:: 0.1.0
+ """
+ returnself.xa_elem.productVersion()@property
- defscheme(self)->str:
- returnself.xa_elem.scheme()
+ defshort_version(self)->'str':
+ """The short version of the application bundle referenced by the alias.
+
+ .. versionadded:: 0.1.0
+ """
+ returnself.xa_elem.shortVersion()@property
- deffragment(self)->str:
- returnself.xa_elem.fragment()
+ defstationery(self)->'bool':
+ """Whether the alias is a stationery pad.
+
+ .. versionadded:: 0.1.0
+ """
+ returnself.xa_elem.stationery()@property
- defhtml(self)->element.Tag:
- ifself.soupisNone:
- self.__get_soup()
- returnself.soup.html
+ deftype_identifier(self)->'str':
+ """The type identifier of the alias.
+
+ .. versionadded:: 0.1.0
+ """
+ returnself.xa_elem.typeIdentifier()@property
- deftitle(self)->str:
- ifself.soupisNone:
- self.__get_soup()
- returnself.soup.title.text
+ defversion(self)->'str':
+ """The version of the application bundle referenced by the alias (visible at the bottom of the "Get Info" window).
- def__get_soup(self):
- req=requests.get(str(self.xa_elem))
- self.soup=BeautifulSoup(req.text,"html.parser")
+ .. versionadded:: 0.1.0
+ """
+ returnself.xa_elem.version()
-
[docs]defopen(self):
- """Opens the URL in the appropriate default application.
+
[docs]defaliases(self,filter:Union[dict,None]=None)->'XAAliasList':
+ """Returns a list of aliases, as PyXA objects, matching the given filter.
- .. versionadded:: 0.0.5
+ .. versionadded:: 0.1.0 """
- AppKit.NSWorkspace.sharedWorkspace().openURL_(self.xa_elem)
[docs]defextract_text(self)->List[str]:
- """Extracts the visible text from the webpage that the URL points to.
+
[docs]defdisk_items(self,filter:Union[dict,None]=None)->'XADiskItemList':
+ """Returns a list of disk items, as PyXA objects, matching the given filter.
- :return: The list of extracted lines of text
- :rtype: List[str]
+ .. versionadded:: 0.1.0
+ """
+ self._new_element(self.xa_elem.diskItems(),XADiskItemList,filter)
- .. versionadded:: 0.0.8
+
[docs]deffiles(self,filter:Union[dict,None]=None)->'XAFileList':
+ """Returns a list of files, as PyXA objects, matching the given filter.
+
+ .. versionadded:: 0.1.0 """
- ifself.soupisNone:
- self.__get_soup()
- returnself.soup.get_text().splitlines()
[docs]defextract_images(self)->List['XAImage']:
- """Extracts all images from HTML of the webpage that the URL points to.
+
[docs]deffile_packages(self,filter:Union[dict,None]=None)->'XAFilePackageList':
+ """Returns a list of file packages, as PyXA objects, matching the given filter.
- :return: The list of extracted images
- :rtype: List[XAImage]
+ .. versionadded:: 0.1.0
+ """
+ self._new_element(self.xa_elem.filePackages(),XAFilePackageList,filter)
- .. versionadded:: 0.0.8
+
[docs]deffolders(self,filter:Union[dict,None]=None)->'XAFolderList':
+ """Returns a list of folders, as PyXA objects, matching the given filter.
+
+ .. versionadded:: 0.1.0 """
- data=AppKit.NSData.alloc().initWithContentsOfURL_(AppKit.NSURL.URLWithString_(str(self.xa_elem)))
- image=AppKit.NSImage.alloc().initWithData_(data)
+ self._new_element(self.xa_elem.folders(),XAFolderList,filter)
[docs]classXADiskList(XADiskItemList):
+ """A wrapper around lists of disks that employs fast enumeration techniques.
-
[docs]defget_clipboard_representation(self)->List[Union[AppKit.NSURL,str]]:
- """Gets a clipboard-codable representation of the URL.
+ All properties of disks can be called as methods on the wrapped list, returning a list containing each disk's value for the property.
- When the clipboard content is set to a URL, the raw URL data and the string representation of the URL are added to the clipboard.
+ .. versionadded:: 0.1.0
+ """
+ def__init__(self,properties:dict,filter:Union[dict,None]=None):
+ super().__init__(properties,filter,XADisk)
- :return: The clipboard-codable form of the URL
- :rtype: Any
+
[docs]defcapacity(self)->list['float']:
+ """Retrieves the total number of bytes (free or used) on each disk in the list.
- .. versionadded:: 0.0.8
+ .. versionadded:: 0.1.0 """
- return[self.xa_elem,str(self.xa_elem)]
[docs]defejectable(self)->list['bool']:
+ """Retrieves the ejectable status of each disk in the list.
+ .. versionadded:: 0.1.0
+ """
+ returnlist(self.xa_elem.arrayByApplyingSelector_("ejectable"))
+
[docs]defformat(self)->list['XAEventsApplication.Format']:
+ """Retrieves the file system format of each disk in the list.
+ .. versionadded:: 0.1.0
+ """
+ ls=self.xa_elem.arrayByApplyingSelector_("format")
+ return[XAEventsApplication.Format(OSType(x.stringValue()))forxinls]
-
[docs]classXAPath(XAObject,XAClipboardCodable):
- """A path to a file on the disk.
+
[docs]deffree_space(self)->list['float']:
+ """Retrieves the number of free bytes left on each disk in the list.
- .. versionadded:: 0.0.5
- """
- def__init__(self,path:Union[str,AppKit.NSURL]):
- super().__init__()
- ifisinstance(path,str):
- path=AppKit.NSURL.alloc().initFileURLWithPath_(path)
- self.xa_elem=path
- self.path=path.path()#: The path string without the file:// prefix
- self.xa_wksp=AppKit.NSWorkspace.sharedWorkspace()
+ .. versionadded:: 0.1.0
+ """
+ returnlist(self.xa_elem.arrayByApplyingSelector_("freeSpace"))
-
[docs]defopen(self):
- """Opens the file in its default application.
+
[docs]defignore_privileges(self)->list['bool']:
+ """Retrieves the ignore privileges status for each disk in the list.
- .. versionadded: 0.0.5
+ .. versionadded:: 0.1.0 """
- self.xa_wksp.openURL_(self.xa_elem)
[docs]defshow_in_finder(self):
- """Opens a Finder window showing the folder containing this path, with the associated file selected. Synonymous with :func:`select`.
+
[docs]deflocal_volume(self)->list['bool']:
+ """Retrieves the local volume status for each disk in the list.
- .. versionadded: 0.0.9
+ .. versionadded:: 0.1.0 """
- self.select()
[docs]defselect(self):
- """Opens a Finder window showing the folder containing this path, with the associated file selected. Synonymous with :func:`show_in_finder`.
+
[docs]defserver(self)->list['str']:
+ """Retrieves the server on which each disk in the list resides, AFP volumes only.
- .. versionadded: 0.0.5
+ .. versionadded:: 0.1.0 """
- self.xa_wksp.activateFileViewerSelectingURLs_([self.xa_elem])
[docs]defget_clipboard_representation(self)->List[Union[AppKit.NSURL,str]]:
- """Gets a clipboard-codable representation of the path.
+
[docs]defstartup(self)->list['bool']:
+ """Retrieves the startup disk status of each disk in the list.
- 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.
+ .. versionadded:: 0.1.0
+ """
+ returnlist(self.xa_elem.arrayByApplyingSelector_("startup"))
- :return: The clipboard-codable form of the path
- :rtype: Any
+
[docs]defzone(self)->list['str']:
+ """Retrieves the zone in which each disk's server resides, AFP volumes only.
- .. versionadded:: 0.0.8
+ .. versionadded:: 0.1.0 """
- return[self.xa_elem,self.xa_elem.path()]
[docs]defby_capacity(self,capacity:float)->'XADisk':
+ """Retrieves the disk whose capacity matches the given capacity.
+ .. versionadded:: 0.1.0
+ """
+ returnself.by_property("capacity",capacity)
+
[docs]defby_ejectable(self,ejectable:bool)->'XADisk':
+ """Retrieves the disk whose ejectable status matches the given boolean value.
+ .. versionadded:: 0.1.0
+ """
+ returnself.by_property("ejectable",ejectable)
-
[docs]classXAPredicate(XAObject,XAClipboardCodable):
- """A predicate used to filter arrays.
+
[docs]defby_format(self,format:'XAEventsApplication.Format')->'XADisk':
+ """Retrieves the disk whose format matches the given format.
- .. versionadded:: 0.0.4
- """
- def__init__(self):
- self.keys:List[str]=[]
- self.operators:List[str]=[]
- self.values:List[str]=[]
+ .. versionadded:: 0.1.0
+ """
+ returnself.by_property("format",format.value)
-
[docs]deffrom_dict(self,ref_dict:dict)->'XAPredicate':
- """Populates the XAPredicate object from the supplied dictionary.
+
[docs]defby_free_space(self,free_space:float)->'XADisk':
+ """Retrieves the disk whose free space matches the given amount.
- The predicate will use == for all comparisons.
+ .. versionadded:: 0.1.0
+ """
+ returnself.by_property("freeSpace",free_space)
- :param ref_dict: A specification of key, value pairs
- :type ref_dict: dict
- :return: The populated predicate object
- :rtype: XAPredicate
+
[docs]defby_ignore_privileges(self,ignore_privileges:bool)->'XADisk':
+ """Retrieves the disk whose ignore privileges status matches the given boolean value.
- .. versionadded:: 0.0.4
+ .. versionadded:: 0.1.0 """
- forkey,valueinref_dict.items():
- self.keys.append(key)
- self.operators.append("==")
- self.values.append(value)
- returnself
[docs]deffrom_args(self,*args)->'XAPredicate':
- """Populates the XAPredicate object from the supplied key, value argument pairs.
+
[docs]defby_local_volume(self,local_volume:bool)->'XADisk':
+ """Retrieves the disk whose local volume status matches the given boolean value.
- The number of keys and values must be equal. The predicate will use == for all comparisons.
+ .. versionadded:: 0.1.0
+ """
+ returnself.by_property("localVolume",local_volume)
- :raises InvalidPredicateError: Raised when the number of keys does not match the number of values
- :return: The populated predicate object
- :rtype: XAPredicate
+
[docs]defby_server(self,server:str)->'XADisk':
+ """Retrieves the disk whose server matches the given server.
- .. versionadded:: 0.0.4
+ .. versionadded:: 0.1.0 """
- arg_num=len(args)
- ifarg_num%2!=0:
- raiseInvalidPredicateError("The number of keys and values must be equal; the number of arguments must be an even number.")
-
- forindex,valueinenumerate(args):
- ifindex%2==0:
- self.keys.append(value)
- self.operators.append("==")
- self.values.append(args[index+1])
- returnself
+ returnself.by_property("server",server)
-
[docs]defevaluate(self,target:AppKit.NSArray)->AppKit.NSArray:
- """Evaluates the predicate on the given array.
+
[docs]defby_startup(self,startup:bool)->'XADisk':
+ """Retrieves the disk whose startup status matches the given boolean value.
- :param target: The array to evaluate against the predicate
- :type target: AppKit.NSArray
- :return: The filtered array
- :rtype: AppKit.NSArray
+ .. versionadded:: 0.1.0
+ """
+ returnself.by_property("startup",startup)
- .. versionadded:: 0.0.4
+
[docs]defby_zone(self,zone:str)->'XADisk':
+ """Retrieves the disk whose zone matches the given zone.
+
+ .. versionadded:: 0.1.0 """
- placeholders=["%@"]*len(self.values)
- expressions=[" ".join(expr)forexprinzip(self.keys,self.operators,placeholders)]
- format="( "+" ) && ( ".join(expressions)+" )"
- predicate=AppKit.NSPredicate.predicateWithFormat_(format,*self.values)
- returntarget.filteredArrayUsingPredicate_(predicate)
+ returnself.by_property("zone",zone)
-
[docs]defevaluate_with_format(target:AppKit.NSArray,fmt:str)->AppKit.NSArray:
- """Evaluates the specified array against a predicate with the given format.
+
[docs]classXADisk(XADiskItem):
+ """A disk in the file system.
- :param target: The array to filter
- :type target: AppKit.NSArray
- :param fmt: The format string for the predicate
- :type fmt: str
- :return: The filtered array
- :rtype: AppKit.NSArray
+ .. versionadded:: 0.1.0
+ """
+ def__init__(self,properties):
+ super().__init__(properties)
- .. versionadded:: 0.0.4
+ @property
+ defcapacity(self)->'float':
+ """The total number of bytes (free or used) on the disk.
+
+ .. versionadded:: 0.1.0 """
- predicate=AppKit.NSPredicate.predicateWithFormat_(fmt)
- returntarget.filteredArrayUsingPredicate_(predicate)
+ returnself.xa_elem.capacity()
-
[docs]defevaluate_with_dict(target:AppKit.NSArray,properties_dict:dict)->AppKit.NSArray:
- """Evaluates the specified array against a predicate constructed from the supplied dictionary.
+ @property
+ defejectable(self)->'bool':
+ """Whether the media can be ejected (floppies, CD's, and so on).
- The predicate will use == for all comparisons.
+ .. versionadded:: 0.1.0
+ """
+ returnself.xa_elem.ejectable()
- :param target: The array to filter
- :type target: AppKit.NSArray
- :param properties_dict: The specification of key, value pairs
- :type properties_dict: dict
- :return: The filtered array
- :rtype: AppKit.NSArray
+ @property
+ defformat(self)->'XAEventsApplication.Format':
+ """The file system format of the disk.
- .. versionadded:: 0.0.4
+ .. versionadded:: 0.1.0 """
- fmt=""
- forkey,valueinproperties_dict.items():
- ifisinstance(value,str):
- value="'"+value+"'"
- fmt+=f"( {key} == {value} ) &&"
- predicate=AppKit.NSPredicate.predicateWithFormat_(fmt[:-3])
- returntarget.filteredArrayUsingPredicate_(predicate)
[docs]defadd_eq_condition(self,property:str,value:Any):
- """Appends an `==` condition to the end of the predicate format.
+ @property
+ deffree_space(self)->'float':
+ """The number of free bytes left on the disk.
- The added condition will have the form `property == value`.
+ .. versionadded:: 0.1.0
+ """
+ returnself.xa_elem.freeSpace()
- :param property: A property of an object to check the condition against
- :type property: str
- :param value: The target value of the condition
- :type value: Any
+ @property
+ defignore_privileges(self)->'bool':
+ """Whether to ignore permissions on this disk.
- .. versionadded:: 0.0.4
+ .. versionadded:: 0.1.0 """
- self.keys.append(property)
- self.operators.append("==")
- self.values.append(value)
+ returnself.xa_elem.ignorePrivileges()
-
[docs]definsert_eq_condition(self,index:int,property:str,value:Any):
- """Inserts an `==` condition to the predicate format at the desired location, specified by index.
+ @property
+ deflocal_volume(self)->'bool':
+ """Whether the media is a local volume (as opposed to a file server).
- The added condition will have the form `property == value`.
+ .. versionadded:: 0.1.0
+ """
+ returnself.xa_elem.localVolume()
- :param property: A property of an object to check the condition against
- :type property: str
- :param value: The target value of the condition
- :type value: Any
+ @property
+ defserver(self)->'str':
+ """The server on which the disk resides, AFP volumes only.
- .. versionadded:: 0.0.4
+ .. versionadded:: 0.1.0 """
- self.keys.insert(index,property)
- self.operators.insert(index,"==")
- self.values.insert(index,value)
+ returnself.xa_elem.server()
+
+ @property
+ defstartup(self)->'bool':
+ """Whether this disk is the boot disk.
+
+ .. versionadded:: 0.1.0
+ """
+ returnself.xa_elem.startup()
+
+ @property
+ defzone(self)->'str':
+ """The zone in which the disk's server resides, AFP volumes only.
+
+ .. versionadded:: 0.1.0
+ """
+ returnself.xa_elem.zone()
+
+
[docs]defaliases(self,filter:Union[dict,None]=None)->'XAAliasList':
+ """Returns a list of aliases, as PyXA objects, matching the given filter.
+
+ .. versionadded:: 0.1.0
+ """
+ self._new_element(self.xa_elem.aliases(),XAAliasList,filter)
- # NOT EQUAL
-
[docs]defadd_neq_condition(self,property:str,value:Any):
- """Appends a `!=` condition to the end of the predicate format.
+
[docs]defdisk_items(self,filter:Union[dict,None]=None)->'XADiskItemList':
+ """Returns a list of disk items, as PyXA objects, matching the given filter.
- The added condition will have the form `property != value`.
+ .. versionadded:: 0.1.0
+ """
+ self._new_element(self.xa_elem.diskItems(),XADiskItemList,filter)
- :param property: A property of an object to check the condition against
- :type property: str
- :param value: The target value of the condition
- :type value: Any
+
[docs]deffiles(self,filter:Union[dict,None]=None)->'XAFileList':
+ """Returns a list of files, as PyXA objects, matching the given filter.
- .. versionadded:: 0.0.4
+ .. versionadded:: 0.1.0 """
- self.keys.append(property)
- self.operators.append("!=")
- self.values.append(value)
[docs]definsert_neq_condition(self,index:int,property:str,value:Any):
- """Inserts a `!=` condition to the predicate format at the desired location, specified by index.
+
[docs]deffile_packages(self,filter:Union[dict,None]=None)->'XAFilePackageList':
+ """Returns a list of file packages, as PyXA objects, matching the given filter.
- The added condition will have the form `property != value`.
+ .. versionadded:: 0.1.0
+ """
+ self._new_element(self.xa_elem.fileOackages(),XAFilePackageList,filter)
- :param property: A property of an object to check the condition against
- :type property: str
- :param value: The target value of the condition
- :type value: Any
+
[docs]deffolders(self,filter:Union[dict,None]=None)->'XAFolderList':
+ """Returns a list of folders, as PyXA objects, matching the given filter.
- .. versionadded:: 0.0.4
+ .. versionadded:: 0.1.0 """
- self.keys.insert(index,property)
- self.operators.insert(index,"!=")
- self.values.insert(index,value)
[docs]defadd_geq_condition(self,property:str,value:Any):
- """Appends a `>=` condition to the end of the predicate format.
- The added condition will have the form `property >= value`.
- :param property: A property of an object to check the condition against
- :type property: str
- :param value: The target value of the condition
- :type value: Any
- .. versionadded:: 0.0.4
- """
- self.keys.append(property)
- self.operators.append(">=")
- self.values.append(value)
+
[docs]classXADomainList(XAList):
+ """A wrapper around lists of domains that employs fast enumeration techniques.
-
[docs]definsert_geq_condition(self,index:int,property:str,value:Any):
- """Inserts a `>=` condition to the predicate format at the desired location, specified by index.
+ All properties of domains can be called as methods on the wrapped list, returning a list containing each domain's value for the property.
- The added condition will have the form `property >= value`.
+ .. versionadded:: 0.1.0
+ """
+ def__init__(self,properties:dict,filter:Union[dict,None]=None):
+ super().__init__(properties,XADomain,filter)
- :param property: A property of an object to check the condition against
- :type property: str
- :param value: The target value of the condition
- :type value: Any
+
[docs]defid(self)->list['str']:
+ """Retrieves the unique identifier of each domain in the list
- .. versionadded:: 0.0.4
+ .. versionadded:: 0.1.0 """
- self.keys.insert(index,property)
- self.operators.insert(index,">=")
- self.values.insert(index,value)
[docs]defadd_leq_condition(self,property:str,value:Any):
- """Appends a `<=` condition to the end of the predicate format.
+
[docs]defname(self)->list['str']:
+ """Retrieves the name of each domain in the list.
- The added condition will have the form `property <= value`.
+ .. versionadded:: 0.1.0
+ """
+ returnlist(self.xa_elem.arrayByApplyingSelector_("name"))
- :param property: A property of an object to check the condition against
- :type property: str
- :param value: The target value of the condition
- :type value: Any
+
[docs]defby_id(self,id:str)->'XADomain':
+ """Retrieves the domain whose ID matches the given ID.
- .. versionadded:: 0.0.4
+ .. versionadded:: 0.1.0 """
- self.keys.append(property)
- self.operators.append("<=")
- self.values.append(value)
+ returnself.by_property("id",id)
-
[docs]definsert_leq_condition(self,index:int,property:str,value:Any):
- """Inserts a `<=` condition to the predicate format at the desired location, specified by index.
+
[docs]defby_name(self,name:str)->'XADomain':
+ """Retrieves the domain whose name matches the given name.
- The added condition will have the form `property <= value`.
+ .. versionadded:: 0.1.0
+ """
+ returnself.by_property("name",name)
- :param property: A property of an object to check the condition against
- :type property: str
- :param value: The target value of the condition
- :type value: Any
+ def__repr__(self):
+ return"<"+str(type(self))+str(self.name())+">"
[docs]classXADomain(XAObject):
+ """A domain in the file system.
- # GREATER THAN
-
[docs]defadd_gt_condition(self,property:str,value:Any):
- """Appends a `>` condition to the end of the predicate format.
+ .. versionadded:: 0.1.0
+ """
+ def__init__(self,properties):
+ super().__init__(properties)
- The added condition will have the form `property > value`.
+ @property
+ defapplication_support_folder(self)->'XAFolder':
+ """The Application Support folder.
- :param property: A property of an object to check the condition against
- :type property: str
- :param value: The target value of the condition
- :type value: Any
+ .. versionadded:: 0.1.0
+ """
+ returnself._new_element(self.xa_elem.applicationSupportFolder(),XAFolder)
- .. versionadded:: 0.0.4
+ @property
+ defapplications_folder(self)->'XAFolder':
+ """The Applications folder.
+
+ .. versionadded:: 0.1.0 """
- self.keys.append(property)
- self.operators.append(">")
- self.values.append(value)
[docs]definsert_gt_condition(self,index:int,property:str,value:Any):
- """Inserts a `>` condition to the predicate format at the desired location, specified by index.
+ @property
+ defdesktop_pictures_folder(self)->'XAFolder':
+ """The Desktop Pictures folder.
- The added condition will have the form `property > value`.
+ .. versionadded:: 0.1.0
+ """
+ returnself._new_element(self.xa_elem.desktopPicturesFolder(),XAFolder)
- :param property: A property of an object to check the condition against
- :type property: str
- :param value: The target value of the condition
- :type value: Any
+ @property
+ deffolder_action_scripts_folder(self)->'XAFolder':
+ """The Folder Action Scripts folder.
- .. versionadded:: 0.0.4
+ .. versionadded:: 0.1.0 """
- self.keys.insert(index,property)
- self.operators.insert(index,">")
- self.values.insert(index,value)
+ returnself._new_element(self.xa_elem.folderActionScriptsFolder(),XAFolder)
- # LESS THAN
-
[docs]defadd_lt_condition(self,property:str,value:Any):
- """Appends a `<` condition to the end of the predicate format.
+ @property
+ deffonts_folder(self)->'XAFolder':
+ """The Fonts folder.
- The added condition will have the form `property < value`.
+ .. versionadded:: 0.1.0
+ """
+ returnself._new_element(self.xa_elem.fontsFolder(),XAFolder)
- :param property: A property of an object to check the condition against
- :type property: str
- :param value: The target value of the condition
- :type value: Any
+ @property
+ defid(self)->'str':
+ """The unique identifier of the domain.
- .. versionadded:: 0.0.4
+ .. versionadded:: 0.1.0 """
- self.keys.append(property)
- self.operators.append("<")
- self.values.append(value)
+ returnself.xa_elem.id()
-
[docs]definsert_lt_condition(self,index:int,property:str,value:Any):
- """Inserts a `<` condition to the predicate format at the desired location, specified by index.
+ @property
+ deflibrary_folder(self)->'XAFolder':
+ """The Library folder.
- The added condition will have the form `property < value`.
+ .. versionadded:: 0.1.0
+ """
+ returnself._new_element(self.xa_elem.libraryFolder(),XAFolder)
- :param property: A property of an object to check the condition against
- :type property: str
- :param value: The target value of the condition
- :type value: Any
+ @property
+ defname(self)->'str':
+ """The name of the domain.
- .. versionadded:: 0.0.4
+ .. versionadded:: 0.1.0 """
- self.keys.insert(index,property)
- self.operators.insert(index,"<")
- self.values.insert(index,value)
+ returnself.xa_elem.name()
- # BETWEEN
-
[docs]defadd_between_condition(self,property:str,value1:Any,value2:Any):
- """Appends a `BETWEEN` condition to the end of the predicate format.
+ @property
+ defpreferences_folder(self)->'XAFolder':
+ """The Preferences folder.
- The added condition will have the form `property BETWEEN [value1, value2]`.
+ .. versionadded:: 0.1.0
+ """
+ returnself._new_element(self.xa_elem.preferencesFolder(),XAFolder)
- :param property: A property of an object to check the condition against
- :type property: str
- :param value: The target value of the condition
- :type value: Any
+ @property
+ defscripting_additions_folder(self)->'XAFolder':
+ """The Scripting Additions folder.
- .. versionadded:: 0.0.4
+ .. versionadded:: 0.1.0 """
- self.keys.append(property)
- self.operators.append("BETWEEN")
- self.values.append([value1,value2])
[docs]definsert_between_condition(self,index:int,property:str,value1:Any,value2:Any):
- """Inserts a `BETWEEN` condition to the predicate format at the desired location, specified by index.
+ @property
+ defscripts_folder(self)->'XAFolder':
+ """The Scripts folder.
- The added condition will have the form `property BETWEEN [value1, value2]`.
+ .. versionadded:: 0.1.0
+ """
+ returnself._new_element(self.xa_elem.scriptsFolder(),XAFolder)
- :param property: A property of an object to check the condition against
- :type property: str
- :param value: The target value of the condition
- :type value: Any
+ @property
+ defshared_documents_folder(self)->'XAFolder':
+ """The Shared Documents folder.
- .. versionadded:: 0.0.4
+ .. versionadded:: 0.1.0 """
- self.keys.insert(index,property)
- self.operators.insert(index,"BETWEEN")
- self.values.insert(index,[value1,value2])
[docs]defadd_begins_with_condition(self,property:str,value:Any):
- """Appends a `BEGINSWITH` condition to the end of the predicate format.
+ @property
+ defspeakable_items_folder(self)->'XAFolder':
+ """The Speakable Items folder.
- The added condition will have the form `property BEGINSWITH value`.
+ .. versionadded:: 0.1.0
+ """
+ returnself._new_element(self.xa_elem.speakableItemsFolder(),XAFolder)
- :param property: A property of an object to check the condition against
- :type property: str
- :param value: The target value of the condition
- :type value: Any
+ @property
+ defutilities_folder(self)->'XAFolder':
+ """The Utilities folder.
- .. versionadded:: 0.0.4
+ .. versionadded:: 0.1.0 """
- self.keys.append(property)
- self.operators.append("BEGINSWITH")
- self.values.append(value)
[docs]definsert_begins_with_condition(self,index:int,property:str,value:Any):
- """Inserts a `BEGINSWITH` condition to the predicate format at the desired location, specified by index.
+ @property
+ defworkflows_folder(self)->'XAFolder':
+ """The Automator Workflows folder.
- The added condition will have the form `property BEGINSWITH value`.
+ .. versionadded:: 0.1.0
+ """
+ returnself._new_element(self.xa_elem.workflowsFolder(),XAFolder)
- :param property: A property of an object to check the condition against
- :type property: str
- :param value: The target value of the condition
- :type value: Any
+
[docs]deffolders(self,filter:Union[dict,None]=None)->'XAFolderList':
+ """Returns a list of folders, as PyXA objects, matching the given filter.
- .. versionadded:: 0.0.4
+ .. versionadded:: 0.1.0 """
- self.keys.insert(index,property)
- self.operators.insert(index,"BEGINSWITH")
- self.values.insert(index,value)
[docs]defadd_ends_with_condition(self,property:str,value:Any):
- """Appends a `ENDSWITH` condition to the end of the predicate format.
+ def__repr__(self):
+ return"<"+str(type(self))+str(self.name)+">"
- The added condition will have the form `property ENDSWITH value`.
- :param property: A property of an object to check the condition against
- :type property: str
- :param value: The target value of the condition
- :type value: Any
- .. versionadded:: 0.0.4
- """
- self.keys.append(property)
- self.operators.append("ENDSWITH")
- self.values.append(value)
-
[docs]definsert_ends_with_condition(self,index:int,property:str,value:Any):
- """Inserts a `ENDSWITH` condition to the predicate format at the desired location, specified by index.
+
[docs]classXAClassicDomainObject(XADomain):
+ """The Classic domain in the file system.
- The added condition will have the form `property ENDSWITH value`.
+ .. versionadded:: 0.1.0
+ """
+ def__init__(self,properties):
+ super().__init__(properties)
- :param property: A property of an object to check the condition against
- :type property: str
- :param value: The target value of the condition
- :type value: Any
+ @property
+ defapple_menu_folder(self)->'XAFolder':
+ """The Apple Menu Items folder.
- .. versionadded:: 0.0.4
+ .. versionadded:: 0.1.0 """
- self.keys.insert(index,property)
- self.operators.insert(index,"ENDSWITH")
- self.values.insert(index,value)
[docs]defadd_contains_condition(self,property:str,value:Any):
- """Appends a `CONTAINS` condition to the end of the predicate format.
+ @property
+ defcontrol_panels_folder(self)->'XAFolder':
+ """The Control Panels folder.
- The added condition will have the form `property CONTAINS value`.
+ .. versionadded:: 0.1.0
+ """
+ returnself._new_element(self.xa_elem.controlPanelsFolder(),XAFolder)
- :param property: A property of an object to check the condition against
- :type property: str
- :param value: The target value of the condition
- :type value: Any
+ @property
+ defcontrol_strip_modules_folder(self)->'XAFolder':
+ """The Control Strip Modules folder.
- .. versionadded:: 0.0.4
+ .. versionadded:: 0.1.0 """
- self.keys.append(property)
- self.operators.append("CONTAINS")
- self.values.append(value)
[docs]defadd_match_condition(self,property:str,value:Any):
- """Appends a `MATCHES` condition to the end of the predicate format.
+ @property
+ deflauncher_items_folder(self)->'XAFolder':
+ """The Launcher Items folder.
- The added condition will have the form `property MATCHES value`.
+ .. versionadded:: 0.1.0
+ """
+ returnself._new_element(self.xa_elem.launcherItemsFolder(),XAFolder)
- :param property: A property of an object to check the condition against
- :type property: str
- :param value: The target value of the condition
- :type value: Any
+ @property
+ defpreferences_folder(self)->'XAFolder':
+ """The Classic Preferences folder.
- .. versionadded:: 0.0.4
+ .. versionadded:: 0.1.0 """
- self.keys.append(property)
- self.operators.append("MATCHES")
- self.values.append(value)
[docs]definsert_match_condition(self,index:int,property:str,value:Any):
- """Inserts a `MATCHES` condition to the predicate format at the desired location, specified by index.
+ @property
+ defshutdown_folder(self)->'XAFolder':
+ """The Shutdown Items folder.
- The added condition will have the form `property MATCHES value`.
+ .. versionadded:: 0.1.0
+ """
+ returnself._new_element(self.xa_elem.shutdownFolder(),XAFolder)
- :param property: A property of an object to check the condition against
- :type property: str
- :param value: The target value of the condition
- :type value: Any
+ @property
+ defstartup_items_folder(self)->'XAFolder':
+ """The StartupItems folder.
- .. versionadded:: 0.0.4
+ .. versionadded:: 0.1.0 """
- self.keys.insert(index,property)
- self.operators.insert(index,"MATCHES")
- self.values.insert(index,value)
[docs]defget_clipboard_representation(self)->str:
- """Gets a clipboard-codable representation of the predicate.
+ @property
+ defsystem_folder(self)->'XAFolder':
+ """The System folder.
- When a predicate is copied to the clipboard, the string representation of the predicate is added to the clipboard.
+ .. versionadded:: 0.1.0
+ """
+ returnself._new_element(self.xa_elem.systemFolder(),XAFolder)
- :return: The string representation of the predicate
- :rtype: str
+
[docs]deffolders(self,filter:Union[dict,None]=None)->'XAFolderList':
+ """Returns a list of folders, as PyXA objects, matching the given filter.
- .. versionadded:: 0.0.8
+ .. versionadded:: 0.1.0 """
- placeholders=["%@"]*len(self.values)
- expressions=[" ".join(expr)forexprinzip(self.keys,self.operators,placeholders)]
- format="( "+" ) && ( ".join(expressions)+" )"
- predicate=AppKit.NSPredicate.predicateWithFormat_(format,*self.values)
- returnpredicate.predicateFormat()
[docs]classXAUIElementList(XAList):
- """A wrapper around a list of UI elements.
+
[docs]classXAFileList(XADiskItemList):
+ """A wrapper around lists of files that employs fast enumeration techniques.
- All properties of UI elements can be accessed via methods on this list, returning a list of the method's return value for each element in the list.
+ All properties of files can be called as methods on the wrapped list, returning a list containing each file's value for the property.
- .. versionadded:: 0.0.5
+ .. versionadded:: 0.1.0 """
- def__init__(self,properties:dict,filter:Union[dict,None]=None,obj_type=None):
- ifobj_typeisNone:
- obj_type=XAUIElement
- super().__init__(properties,obj_type,filter)
+ def__init__(self,properties:dict,filter:Union[dict,None]=None,object_class=None):
+ ifobject_classisNone:
+ object_class=XAFile
+ super().__init__(properties,filter,object_class)
-
[docs]defby_default_application(self,default_application:'XADiskItem')->'XAFile':
+ """Retrieves the file whose default application matches the given application.
-
[docs]defby_type_identifier(self,type_identifier:str)->'XAFile':
+ """Retrieves the file whose type identifier matches the given type identifier.
+
+ .. versionadded:: 0.1.0
+ """
+ returnself.by_property("typeIdentifier",type_identifier)
+
+
[docs]defby_version(self,version:str)->'XAFile':
+ """Retrieves the file whose version matches the given version.
+
+ .. versionadded:: 0.1.0
+ """
+ returnself.by_property("version",version)
+
+
[docs]classXAFile(XADiskItem):
+ """A file in the file system.
+
+ .. versionadded:: 0.1.0
+ """def__init__(self,properties):super().__init__(properties)
- self.properties:dict#: All properties of the UI element
- self.accessibility_description:str#: The accessibility description of the element
- self.enabled:bool#: Whether the UI element is currently enabled
- self.entire_contents:Any#: The entire contents of the element
- self.focused:bool#: Whether the window is the currently element
- self.name:str#: The name of the element
- self.title:str#: The title of the element (often the same as its name)
- self.position:Tuple[int,int]#: The position of the top left corner of the element
- self.size:Tuple[int,int]#: The width and height of the element, in pixels
- self.maximum_value:Any#: The maximum value that the element can have
- self.minimum_value:Any#: The minimum value that the element can have
- self.value:Any#: The current value of the element
- self.role:str#: The element's role
- self.role_description:str#: The description of the element's role
- self.subrole:str#: The subrole of the UI element
- self.selected:bool#: Whether the element is currently selected
-
@property
- defproperties(self)->dict:
- returnself.xa_elem.properties()
+ defcreator_type(self)->'str':
+ """The OSType identifying the application that created the file.
- @property
- defaccessibility_description(self)->str:
- returnself.xa_elem.accessibilityDescription()
+ .. versionadded:: 0.1.0
+ """
+ returnself.xa_elem.creatorType()@property
- defenabled(self)->bool:
- returnself.xa_elem.enabled()
+ defdefault_application(self)->'XADiskItem':
+ """The application that will launch if the file is opened.
- @property
- defentire_contents(self)->List[XAObject]:
- ls=self.xa_elem.entireContents()
- return[self._new_element(x,XAUIElement)forxinls]
+ .. versionadded:: 0.1.0
+ """
+ returnself._new_element(self.xa_elem.defaultApplication(),XADiskItem)
- @property
- deffocused(self)->bool:
- returnself.xa_elem.focused()
+ @default_application.setter
+ defdefault_application(self,default_application:XADiskItem):
+ self.set_property('defaultApplication',default_application.xa_elem)@property
- defname(self)->str:
- returnself.xa_elem.name()
+ deffile_type(self)->'str':
+ """The OSType identifying the type of data contained in the file.
- @property
- deftitle(self)->str:
- returnself.xa_elem.title()
+ .. versionadded:: 0.1.0
+ """
+ returnself.xa_elem.fileType()@property
- defposition(self)->Tuple[int,int]:
- returnself.xa_elem.position()
+ defkind(self)->'str':
+ """The kind of file, as shown in Finder.
- @property
- defsize(self)->Tuple[int,int]:
- returnself.xa_elem.size()
+ .. versionadded:: 0.1.0
+ """
+ returnself.xa_elem.kind()@property
- defmaximum_value(self)->Any:
- returnself.xa_elem.maximumValue()
+ defproduct_version(self)->'str':
+ """The version of the product (visible at the top of the "Get Info" window).
- @property
- defminimum_value(self)->Any:
- returnself.xa_elem.minimumValue()
+ .. versionadded:: 0.1.0
+ """
+ returnself.xa_elem.productVersion()@property
- defvalue(self)->Any:
- returnself.xa_elem.value()
+ defshort_version(self)->'str':
+ """The short version of the file.
- @property
- defrole(self)->str:
- returnself.xa_elem.role()
+ .. versionadded:: 0.1.0
+ """
+ returnself.xa_elem.shortVersion()@property
- defrole_description(self)->str:
- returnself.xa_elem.roleDescription()
+ defstationery(self)->'bool':
+ """Whether the file is a stationery pad.
- @property
- defsubrole(self)->str:
- returnself.xa_elem.subrole()
+ .. versionadded:: 0.1.0
+ """
+ returnself.xa_elem.stationery()@property
- defselected(self)->bool:
- returnself.xa_elem.selected()
+ deftype_identifier(self)->'str':
+ """The type identifier of the file.
-
[docs]defdisk_items(self,filter:Union[dict,None]=None)->'XADiskItemList':
+ """Returns a list of disk items, as PyXA objects, matching the given filter.
-
[docs]deffiles(self,filter:Union[dict,None]=None)->'XAFileList':
+ """Returns a list of files, as PyXA objects, matching the given filter.
+ .. versionadded:: 0.1.0
+ """
+ self._new_element(self.xa_elem.files(),XAFileList,filter)
+
[docs]deffile_packages(self,filter:Union[dict,None]=None)->'XAFilePackageList':
+ """Returns a list of file packages, as PyXA objects, matching the given filter.
+ .. versionadded:: 0.1.0
+ """
+ self._new_element(self.xa_elem.filePackages(),XAFilePackageList,filter)
-
[docs]classXAWindowList(XAUIElementList):
- """A wrapper around a list of windows.
+
[docs]deffolders(self,filter:Union[dict,None]=None)->'XAFolderList':
+ """Returns a list of folders, as PyXA objects, matching the given filter.
- .. versionadded:: 0.0.5
- """
- def__init__(self,properties:dict,filter:Union[dict,None]=None):
- super().__init__(properties,filter,XAWindow)
+ .. versionadded:: 0.1.0
+ """
+ self._new_element(self.xa_elem.folders(),XAFolderList,filter)
-
[docs]defcollapse(self):
- """Collapses all windows in the list.
- .. versionadded:: 0.0.5
- """
- forwindowinself:
- window.collapse()
-
[docs]defuncollapse(self):
- """Uncollapses all windows in the list.
- .. versionadded:: 0.0.6
- """
- forwindowinself:
- window.uncollapse()
+
[docs]classXAFolderList(XADiskItemList):
+ """A wrapper around lists of folders that employs fast enumeration techniques.
-
[docs]defclose(self):
- """Closes all windows in the list.add()
-
- .. versionadded:: 0.0.6
- """
- forwindowinself:
- window.close()
+ All properties of folders can be called as methods on the wrapped list, returning a list containing each folder's value for the property.
-
[docs]classXAWindow(XAUIElement):
- """A general window class for windows of both officially scriptable and non-scriptable applications.
+ .. versionadded:: 0.1.0
+ """
+ def__init__(self,properties:dict,filter:Union[dict,None]=None):
+ super().__init__(properties,filter,XAFolder)
- .. seealso:: :class:`XAApplication`
+
[docs]classXAFolder(XADiskItem):
+ """A folder in the file system.
- .. versionadded:: 0.0.1
+ .. versionadded:: 0.1.0 """def__init__(self,properties):super().__init__(properties)
-
[docs]defclose(self)->'XAWindow':
- """Collapses (minimizes) the window.
-
- :return: A reference to the now-collapsed window object.
- :rtype: XAWindow
+
[docs]defaliases(self,filter:Union[dict,None]=None)->'XAAliasList':
+ """Returns a list of aliases, as PyXA objects, matching the given filter.
- .. versionadded:: 0.0.1
+ .. versionadded:: 0.1.0 """
- close_button=self.button({"subrole":"AXCloseButton"})
- close_button.click()
- returnself
-
-
[docs]defcollapse(self)->'XAWindow':
- """Collapses (minimizes) the window.
+ self._new_element(self.xa_elem.aliases(),XAAliasList,filter)
- :return: A reference to the now-collapsed window object.
- :rtype: XAWindow
+
[docs]defdisk_items(self,filter:Union[dict,None]=None)->'XADiskItemList':
+ """Returns a list of disk items, as PyXA objects, matching the given filter.
- .. versionadded:: 0.0.1
+ .. versionadded:: 0.1.0 """
- ifhasattr(self.xa_elem.properties(),"miniaturized"):
- self.xa_elem.setValue_forKey_(True,"miniaturized")
- else:
- close_button=self.buttons({"subrole":"AXMinimizeButton"})[0]
- close_button.click()
- returnself
[docs]defuncollapse(self)->'XAWindow':
- """Uncollapses (unminimizes/expands) the window.
+
[docs]deffiles(self,filter:Union[dict,None]=None)->'XAFileList':
+ """Returns a list of files, as PyXA objects, matching the given filter.
- :return: A reference to the uncollapsed window object.
- :rtype: XAWindow
+ .. versionadded:: 0.1.0
+ """
+ self._new_element(self.xa_elem.files(),XAFileList,filter)
- .. versionadded:: 0.0.1
+
[docs]deffile_packages(self,filter:Union[dict,None]=None)->'XAFilePackageList':
+ """Returns a list of file packages, as PyXA objects, matching the given filter.
+
+ .. versionadded:: 0.1.0 """
- ls=self.xa_sevt.applicationProcesses()
- dock_process=XAPredicate.evaluate_with_format(ls,"name == 'Dock'")[0]
+ self._new_element(self.xa_elem.filePackages(),XAFilePackageList,filter)
[docs]deffolders(self,filter:Union[dict,None]=None)->'XAFolderList':
+ """Returns a list of folders, as PyXA objects, matching the given filter.
+ :param filter: A dictionary specifying property-value pairs that all returned folders will have, or None
+ :type filter: Union[dict, None]
+ :return: The list of folders
+ :rtype: XAFolderList
+ .. versionadded:: 0.1.0
+ """
+ self._new_element(self.xa_elem.folders(),XAFolderList,filter)
-
[docs]classXAUIMenuBarList(XAUIElementList):
- """A wrapper around a list of menu bars.
- .. versionadded:: 0.0.5
- """
- def__init__(self,properties:dict,filter:Union[dict,None]=None):
- super().__init__(properties,filter,XAUIMenuBar)
[docs]classXALocalDomainObject(XADomain):
+ """The local domain in the file system.
+
+ .. versionadded:: 0.1.0 """def__init__(self,properties):super().__init__(properties)
@@ -2740,18 +7549,10 @@
Source code for PyXA.XABase
-
[docs]classXAUIMenuBarItemList(XAUIElementList):
- """A wrapper around a list of menu bar items.
-
- .. versionadded:: 0.0.5
- """
- def__init__(self,properties:dict,filter:Union[dict,None]=None):
- super().__init__(properties,filter,XAUIMenuBarItem)
+
[docs]classXANetworkDomainObject(XADomain):
+ """The network domain in the file system.
-
[docs]classXAUIMenuList(XAUIElementList):
- """A wrapper around a list of menus.
-
- .. versionadded:: 0.0.5
- """
- def__init__(self,properties:dict,filter:Union[dict,None]=None):
- super().__init__(properties,filter,XAUIMenu)
+
[docs]classXASystemDomainObject(XADomain):
+ """The system domain in the file system.
-
[docs]classXAUIMenuItemList(XAUIElementList):
- """A wrapper around a list of menu items.
-
- .. versionadded:: 0.0.5
- """
- def__init__(self,properties:dict,filter:Union[dict,None]=None):
- super().__init__(properties,filter,XAUIMenuItem)
+
[docs]classXAUserDomainObject(XADomain):
+ """The user domain in the file system.
-
[docs]classXAUIGroupList(XAUIElementList):
- """A wrapper around a list of UI element groups.
- .. versionadded:: 0.0.5
- """
- def__init__(self,properties:dict,filter:Union[dict,None]=None):
- super().__init__(properties,filter,XAUIGroup)
-
[docs]classXAUIGroup(XAUIElement):
- """A group of UI element.
-
- .. versionadded:: 0.0.2
+#############
+### Media ###
+#############
+
[docs]classXAImageList(XAList,XAClipboardCodable):
+ """A wrapper around lists of images that employs fast enumeration techniques.
+
+ .. versionadded:: 0.0.3 """
- def__init__(self,properties):
- super().__init__(properties)
+ def__init__(self,properties:dict,filter:Union[dict,None]=None,obj_class=None):
+ ifobj_classisNone:
+ obj_class=XAImage
+ super().__init__(properties,obj_class,filter)
+ self.modified=False#: Whether the list of images has been modified since it was initialized
+ def__partial_init(self):
+ images=[None]*self.xa_elem.count()
+ definit_images(ref,index,stop):
+ ifisinstance(ref,str):
+ ref=AppKit.NSImage.alloc().initWithContentsOfURL_(XAPath(ref).xa_elem)
+ elifisinstance(ref,ScriptingBridge.SBObject):
+ ref=AppKit.NSImage.alloc().initWithContentsOfURL_(XAPath(ref.imageFile().POSIXPath()).xa_elem)
+ elifisinstance(ref,XAObject):
+ ref=AppKit.NSImage.alloc().initWithContentsOfURL_(ref.image_file.posix_path.xa_elem)
+ images[index]=ref
-
[docs]classXAUITabGroupList(XAUIElementList):
- """A wrapper around a list of UI element tab groups.
+ self.xa_elem.enumerateObjectsUsingBlock_(init_images)
+ returnAppKit.NSMutableArray.alloc().initWithArray_(images)
- .. versionadded:: 0.0.5
- """
- def__init__(self,properties:dict,filter:Union[dict,None]=None):
- super().__init__(properties,filter,XAUITabGroup)
[docs]defhorizontal_stitch(self)->'XAImage':
+ """Horizontally stacks each image in the list.
+
+ The first image in the list is placed at the left side of the resulting image.
+
+ :return: The resulting image after stitching
+ :rtype: XAImage
+
+ .. versionadded:: 0.1.0
+ """
+ returnXAImage.horizontal_stitch(self)
+
+
[docs]defvertical_stitch(self)->'XAImage':
+ """Vertically stacks each image in the list.
+ The first image in the list is placed at the bottom side of the resulting image.
+ :return: The resulting image after stitching
+ :rtype: XAImage
+
+ .. versionadded:: 0.1.0
+ """
+ returnXAImage.vertical_stitch(self)
+
[docs]defadditive_composition(self)->'XAImage':
+ """Creates a composition image by adding the color values of each image in the list.
-
[docs]defsubtractive_composition(self)->'XAImage':
+ """Creates a composition image by subtracting the color values of each image in the list successively.
-
[docs]classXAButton(XAUIElement):
- """A button UI element.
-
- .. versionadded:: 0.0.2
- """
- def__init__(self,properties):
- super().__init__(properties)
+ :param images: The images to create the composition from
+ :type images: list[XAImage]
+ :return: The resulting image composition
+ :rtype: XAImage
-
[docs]defedges(self,intensity:float=1.0)->'XAImageList':
+ """Detects the edges in each image of the list and highlights them colorfully, blackening other areas of the images.
+
+ :param intensity: The degree to which edges are highlighted. Higher is brighter. Defaults to 1.0
+ :type intensity: float
+ :return: The resulting images after applying the filter
+ :rtype: XAImageList
+
+ .. versionadded:: 0.1.0 """
- self.actions({"name":"AXPress"})[0].perform()
- returnself
[docs]defpress(self)->'XAButton':
- """Clicks the button. Synonymous with :func:`click`.
+ returnself.__apply_filter(filter_block,intensity)
- :return: The button object
- :rtype: XAButton
+
[docs]defgaussian_blur(self,intensity:float=10)->'XAImageList':
+ """Blurs each image in the list using a Gaussian filter.
- .. versionadded:: 0.0.2
+ :param intensity: The strength of the blur effect, defaults to 10
+ :type intensity: float
+ :return: The resulting images after applying the filter
+ :rtype: XAImageList
+
+ .. versionadded:: 0.1.0
+ """
+ deffilter_block(image,intensity):
+ filter=Quartz.CIFilter.filterWithName_("CIGaussianBlur")
+ filter.setDefaults()
+ filter.setValue_forKey_(intensity,"inputRadius")
+ returnfilter
+
+ returnself.__apply_filter(filter_block,intensity)
+
+
[docs]defreduce_noise(self,noise_level:float=0.02,sharpness:float=0.4)->'XAImageList':
+ """Reduces noise in each image of the list by sharpening areas with a luminance delta below the specified noise level threshold.
+
+ :param noise_level: The threshold for luminance changes in an area below which will be considered noise, defaults to 0.02
+ :type noise_level: float
+ :param sharpness: The sharpness of the resulting images, defaults to 0.4
+ :type sharpness: float
+ :return: The resulting images after applying the filter
+ :rtype: XAImageList
+
+ .. versionadded:: 0.1.0
+ """
+ deffilter_block(image,noise_level,sharpness):
+ filter=Quartz.CIFilter.filterWithName_("CINoiseReduction")
+ filter.setDefaults()
+ filter.setValue_forKey_(noise_level,"inputNoiseLevel")
+ filter.setValue_forKey_(sharpness,"inputSharpness")
+ returnfilter
+
+ returnself.__apply_filter(filter_block,noise_level,sharpness)
+
+
[docs]defpixellate(self,pixel_size:float=8.0)->'XAImageList':
+ """Pixellates each image in the list.
+
+ :param pixel_size: The size of the pixels, defaults to 8.0
+ :type pixel_size: float
+ :return: The resulting images after applying the filter
+ :rtype: XAImageList
+
+ .. versionadded:: 0.1.0 """
- self.actions({"name":"AXPress"})[0].perform()
- returnself
[docs]defoption_click(self)->'XAButton':
- """Option-Clicks the button.
+ returnself.__apply_filter(filter_block,pixel_size)
- :return: The button object
- :rtype: XAButton
+
[docs]defoutline(self,threshold:float=0.1)->'XAImageList':
+ """Outlines detected edges within each image of the list in black, leaving the rest transparent.
- .. versionadded:: 0.0.2
+ :param threshold: The threshold to use when separating edge and non-edge pixels. Larger values produce thinner edge lines. Defaults to 0.1
+ :type threshold: float
+ :return: The resulting images after applying the filter
+ :rtype: XAImageList
+
+ .. versionadded:: 0.1.0 """
- self.actions({"name":"AXZoomWindow"})[0].perform()
- returnself
[docs]defshow_menu(self)->'XAButton':
- """Right clicks the button, invoking a menu.
+ returnself.__apply_filter(filter_block,threshold)
- :return: The button object
- :rtype: XAButton
+
[docs]definvert(self)->'XAImageList':
+ """Inverts the colors of each image in the list.
- .. versionadded:: 0.0.2
+ :return: The resulting images after applying the filter
+ :rtype: XAImageList
+
+ .. versionadded:: 0.1.0 """
- self.actions({"name":"AXShowMenu"})[0].perform()
- returnself
[docs]defsepia(self,intensity:float=1.0)->'XAImageList':
+ """Applies a sepia filter to each image in the list; maps all colors of the images to shades of brown.
+ :param intensity: The opacity of the sepia effect. A value of 0 will have no impact on the image. Defaults to 1.0
+ :type intensity: float
+ :return: The resulting images after applying the filter
+ :rtype: XAImageList
+ .. versionadded:: 0.1.0
+ """
+ deffilter_block(image,intensity):
+ filter=Quartz.CIFilter.filterWithName_("CISepiaTone")
+ filter.setDefaults()
+ filter.setValue_forKey_(intensity,"inputIntensity")
+ returnfilter
-
[docs]classXAUIRadioButtonList(XAUIElementList):
- """A wrapper around lists of radio buttons that employs fast enumeration techniques.
+ returnself.__apply_filter(filter_block,intensity)
+ :param intensity: The intensity of the vignette effect, defaults to 1.0
+ :type intensity: float
+ :return: The resulting images after applying the filter
+ :rtype: XAImageList
+
+ .. versionadded:: 0.1.0
+ """
+ deffilter_block(image,intensity):
+ filter=Quartz.CIFilter.filterWithName_("CIVignette")
+ filter.setDefaults()
+ filter.setValue_forKey_(intensity,"inputIntensity")
+ returnfilter
+
+ returnself.__apply_filter(filter_block,intensity)
+
+
[docs]defdepth_of_field(self,focal_region:Union[tuple[tuple[int,int],tuple[int,int]],None]=None,intensity:float=10.0,focal_region_saturation:float=1.5)->'XAImageList':
+ """Applies a depth of field filter to each image in the list, simulating a tilt & shift effect.
+ :param focal_region: 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
+ :type focal_region: Union[tuple[tuple[int, int], tuple[int, int]], None]
+ :param intensity: 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
+ :type intensity: float
+ :param focal_region_saturation: Adjusts the saturation of the focial region. Higher values increase saturation. Defaults to 1.5 (1.5x default saturation)
+ :type focal_region_saturation: float
+ :return: The resulting images after applying the filter
+ :rtype: XAImageList
+ .. versionadded:: 0.1.0
+ """
+ deffilter_block(image,focal_region,intensity,focal_region_saturation):
+ iffocal_regionisNone:
+ center_top=Quartz.CIVector.vectorWithX_Y_(image.size().width/2,image.size().height/3)
+ center_bottom=Quartz.CIVector.vectorWithX_Y_(image.size().width/2,image.size().height/3*2)
+ focal_region=(center_top,center_bottom)
+ else:
+ point1=Quartz.CIVector.vectorWithX_Y_(focal_region[0])
+ point2=Quartz.CIVector.vectorWithX_Y_(focal_region[1])
+ focal_region=(point1,point2)
+ filter=Quartz.CIFilter.filterWithName_("CIDepthOfField")
+ filter.setDefaults()
+ filter.setValue_forKey_(focal_region[0],"inputPoint0")
+ filter.setValue_forKey_(focal_region[1],"inputPoint1")
+ filter.setValue_forKey_(intensity,"inputRadius")
+ filter.setValue_forKey_(focal_region_saturation,"inputSaturation")
+ returnfilter
-
[docs]classXAUIActionList(XAUIElementList):
- """A wrapper around a list of UI element actions.
+ returnself.__apply_filter(filter_block,focal_region,intensity,focal_region_saturation)
[docs]defcrystallize(self,crystal_size:float=20.0)->'XAImageList':
+ """Applies a crystallization filter to each image in the list. Creates polygon-shaped color blocks by aggregating pixel values.
-
[docs]classXAUIAction(XAUIElement):
- """An action associated with a UI element.
-
- .. versionadded:: 0.0.2
- """
- def__init__(self,properties):
- super().__init__(properties)
+ :param crystal_size: The radius of the crystals, defaults to 20.0
+ :type crystal_size: float
+ :return: The resulting images after applying the filter
+ :rtype: XAImageList
-
[docs]defcomic(self)->'XAImageList':
+ """Applies a comic filter to each image in the list. Outlines edges and applies a color halftone effect.
+ :return: The resulting images after applying the filter
+ :rtype: XAImageList
-
[docs]classXAUITextfieldList(XAUIElementList):
- """A wrapper around a list of textfields.
-
- .. versionadded:: 0.0.5
- """
- def__init__(self,properties:dict,filter:Union[dict,None]=None):
- super().__init__(properties,filter,XAUITextfield)
[docs]defpointillize(self,point_size:float=20.0)->'XAImageList':
+ """Applies a pointillization filter to each image in the list.
+ :param crystal_size: The radius of the points, defaults to 20.0
+ :type crystal_size: float
+ :return: The resulting images after applying the filter
+ :rtype: XAImageList
+ .. versionadded:: 0.1.0
+ """
+ deffilter_block(image,point_size):
+ filter=Quartz.CIFilter.filterWithName_("CIPointillize")
+ filter.setDefaults()
+ filter.setValue_forKey_(point_size,"inputRadius")
+ returnfilter
-
[docs]classXAUIStaticTextList(XAUIElementList):
- """A wrapper around a list of static text elements.
+ returnself.__apply_filter(filter_block,point_size)
+ :param intensity: The strength of the softening and glow effects, defaults to 0.5
+ :type intensity: float
+ :return: The resulting images after applying the filter
+ :rtype: XAImageList
+ .. versionadded:: 0.1.0
+ """
+ deffilter_block(image,intensity):
+ filter=Quartz.CIFilter.filterWithName_("CIBloom")
+ filter.setDefaults()
+ filter.setValue_forKey_(intensity,"inputIntensity")
+ returnfilter
+ returnself.__apply_filter(filter_block,intensity)
+
[docs]defmonochrome(self,color:XAColor,intensity:float=1.0)->'XAImageList':
+ """Remaps the colors of each image in the list to shades of the specified color.
-
[docs]classXATextDocument(XAObject):
- """A class for managing and interacting with text documents.
+ :param color: The color of map each images colors to
+ :type color: XAColor
+ :param intensity: The strength of recoloring effect. Higher values map colors to darker shades of the provided color. Defaults to 1.0
+ :type intensity: float
+ :return: The resulting images after applying the filter
+ :rtype: XAImageList
- .. versionadded:: 0.0.1
- """
- def__init__(self,properties):
- super().__init__(properties)
- self.text:XAText#: The text of the document.
+ .. versionadded:: 0.1.0
+ """
+ ci_color=Quartz.CIColor.alloc().initWithColor_(color.xa_elem)
- @property
- deftext(self)->'XAText':
- returnself._new_element(self.xa_elem.text(),XAText)
+ deffilter_block(image,intensity):
+ filter=Quartz.CIFilter.filterWithName_("CIColorMonochrome")
+ filter.setDefaults()
+ filter.setValue_forKey_(ci_color,"inputColor")
+ filter.setValue_forKey_(intensity,"inputIntensity")
+ returnfilter
-
[docs]defset_text(self,new_text:str)->'XATextDocument':
- """Sets the text of the document.
+ returnself.__apply_filter(filter_block,intensity)
- :param new_text: The new text of the document
- :type new_text: str
- :return: A reference to the document object.
- :rtype: XATextDocument
+
[docs]defbump(self,center:Union[tuple[int,int],None]=None,radius:float=300.0,curvature:float=0.5)->'XAImageList':
+ """Adds a concave (inward) or convex (outward) bump to each image in the list at the specified location within each image.
- .. seealso:: :func:`prepend`, :func:`append`
+ :param center: The center point of the effect, or None to use the center of the image, defaults to None
+ :type center: Union[tuple[int, int], None]
+ :param radius: The radius of the bump in pixels, defaults to 300.0
+ :type radius: float
+ :param curvature: 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
+ :type curvature: float
+ :return: The resulting images after applying the distortion
+ :rtype: XAImageList
- .. versionadded:: 0.0.1
+ .. versionadded:: 0.1.0 """
- self.set_property("text",new_text)
- returnself
+ images=self.__partial_init()
-
[docs]defprepend(self,text:str)->'XATextDocument':
- """Inserts the provided text at the beginning of the document.
+ bumped_images=[None]*images.count()
+ defbump_image(image,index,center,radius,curvature):
+ ifcenterisNone:
+ center=Quartz.CIVector.vectorWithX_Y_(image.size().width/2,image.size().height/2)
+ else:
+ center=Quartz.CIVector.vectorWithX_Y_(center[0],center[1])
+
+ img=Quartz.CIImage.imageWithCGImage_(image.CGImage())
+ filter=Quartz.CIFilter.filterWithName_("CIBumpDistortion")
+ filter.setDefaults()
+ filter.setValue_forKey_(img,"inputImage")
+ filter.setValue_forKey_(center,"inputCenter")
+ filter.setValue_forKey_(radius,"inputRadius")
+ filter.setValue_forKey_(curvature,"inputScale")
+ uncropped=filter.valueForKey_(Quartz.kCIOutputImageKey)
+
+ # Crop the result to the original image size
+ cropped=uncropped.imageByCroppingToRect_(Quartz.CGRectMake(0,0,image.size().width*2,image.size().height*2))
+
+ # Convert back to NSImage
+ rep=AppKit.NSCIImageRep.imageRepWithCIImage_(cropped)
+ result=AppKit.NSImage.alloc().initWithSize_(rep.size())
+ result.addRepresentation_(rep)
+ bumped_images[index]=result
+
+ threads=[None]*images.count()
+ forindex,imageinenumerate(images):
+ threads[index]=self._spawn_thread(bump_image,[image,index,center,radius,curvature])
+
+ whileany([t.is_alive()fortinthreads]):
+ time.sleep(0.01)
- :param text: The text to insert.
- :type text: str
- :return: A reference to the document object.
- :rtype: XATextDocument
+ self.modified=True
+ self.xa_elem=AppKit.NSMutableArray.alloc().initWithArray_(bumped_images)
+ returnself
- .. seealso:: :func:`append`, :func:`set_text`
+
[docs]defpinch(self,center:Union[tuple[int,int],None]=None,intensity:float=0.5)->'XAImageList':
+ """Adds an inward pinch distortion to each image in the list at the specified location within each image.
- .. versionadded:: 0.0.1
+ :param center: The center point of the effect, or None to use the center of the image, defaults to None
+ :type center: Union[tuple[int, int], None]
+ :param intensity: Controls the scale of the pinch effect. Higher values stretch pixels away from the specified center to a greater degree. Defaults to 0.5
+ :type intensity: float
+ :return: The resulting images after applying the distortion
+ :rtype: XAImageList
+
+ .. versionadded:: 0.1.0 """
- old_text=self.text
- self.set_property("text",text+old_text)
- returnself
+ images=self.__partial_init()
-
[docs]defappend(self,text:str)->'XATextDocument':
- """Appends the provided text to the end of the document.
+ pinched_images=[None]*images.count()
+ defpinch_image(image,index,center,intensity):
+ ifcenterisNone:
+ center=Quartz.CIVector.vectorWithX_Y_(image.size().width/2,image.size().height/2)
+ else:
+ center=Quartz.CIVector.vectorWithX_Y_(center[0],center[1])
+
+ img=Quartz.CIImage.imageWithCGImage_(image.CGImage())
+ filter=Quartz.CIFilter.filterWithName_("CIPinchDistortion")
+ filter.setDefaults()
+ filter.setValue_forKey_(img,"inputImage")
+ filter.setValue_forKey_(center,"inputCenter")
+ filter.setValue_forKey_(intensity,"inputScale")
+ uncropped=filter.valueForKey_(Quartz.kCIOutputImageKey)
+
+ # Crop the result to the original image size
+ cropped=uncropped.imageByCroppingToRect_(Quartz.CGRectMake(0,0,image.size().width*2,image.size().height*2))
+
+ # Convert back to NSImage
+ rep=AppKit.NSCIImageRep.imageRepWithCIImage_(cropped)
+ result=AppKit.NSImage.alloc().initWithSize_(rep.size())
+ result.addRepresentation_(rep)
+ pinched_images[index]=result
+
+ threads=[None]*images.count()
+ forindex,imageinenumerate(images):
+ threads[index]=self._spawn_thread(pinch_image,[image,index,center,intensity])
+
+ whileany([t.is_alive()fortinthreads]):
+ time.sleep(0.01)
- :param text: The text to append.
- :type text: str
- :return: A reference to the document object.
- :rtype: XATextDocument
+ self.modified=True
+ self.xa_elem=AppKit.NSMutableArray.alloc().initWithArray_(pinched_images)
+ returnself
[docs]deftwirl(self,center:Union[tuple[int,int],None]=None,radius:float=300.0,angle:float=3.14)->'XAImageList':
+ """Adds a twirl distortion to each image in the list by rotating pixels around the specified location within each image.
- .. versionadded:: 0.0.1
+ :param center: The center point of the effect, or None to use the center of the image, defaults to None
+ :type center: Union[tuple[int, int], None]
+ :param radius: The pixel radius around the centerpoint that defines the area to apply the effect to, defaults to 300.0
+ :type radius: float
+ :param angle: The angle of the twirl in radians, defaults to 3.14
+ :type angle: float
+ :return: The resulting images after applying the distortion
+ :rtype: XAImageList
+
+ .. versionadded:: 0.1.0 """
- old_text=self.text
- self.set_property("text",old_text+text)
+ images=self.__partial_init()
+
+ twirled_images=[None]*images.count()
+ deftwirl_image(image,index,center,radius,angle):
+ ifcenterisNone:
+ center=Quartz.CIVector.vectorWithX_Y_(image.size().width/2,image.size().height/2)
+ else:
+ center=Quartz.CIVector.vectorWithX_Y_(center[0],center[1])
+
+ img=Quartz.CIImage.imageWithCGImage_(image.CGImage())
+ filter=Quartz.CIFilter.filterWithName_("CITwirlDistortion")
+ filter.setDefaults()
+ filter.setValue_forKey_(img,"inputImage")
+ filter.setValue_forKey_(center,"inputCenter")
+ filter.setValue_forKey_(radius,"inputRadius")
+ filter.setValue_forKey_(angle,"inputAngle")
+ uncropped=filter.valueForKey_(Quartz.kCIOutputImageKey)
+
+ # Crop the result to the original image size
+ cropped=uncropped.imageByCroppingToRect_(Quartz.CGRectMake(0,0,image.size().width*2,image.size().height*2))
+
+ # Convert back to NSImage
+ rep=AppKit.NSCIImageRep.imageRepWithCIImage_(cropped)
+ result=AppKit.NSImage.alloc().initWithSize_(rep.size())
+ result.addRepresentation_(rep)
+ twirled_images[index]=result
+
+ threads=[None]*images.count()
+ forindex,imageinenumerate(images):
+ threads[index]=self._spawn_thread(twirl_image,[image,index,center,radius,angle])
+
+ whileany([t.is_alive()fortinthreads]):
+ time.sleep(0.01)
+
+ self.modified=True
+ self.xa_elem=AppKit.NSMutableArray.alloc().initWithArray_(twirled_images)returnself
-
[docs]defreverse(self)->'XATextDocument':
- """Reverses the text of the document.
+
[docs]defauto_enhance(self,correct_red_eye:bool=False,crop_to_features:bool=False,correct_rotation:bool=False)->'XAImageList':
+ """Attempts to enhance each image in the list by applying suggested filters.
- :return: A reference to the document object.
- :rtype: XATextDocument
+ :param correct_red_eye: Whether to attempt red eye removal, defaults to False
+ :type correct_red_eye: bool, optional
+ :param crop_to_features: Whether to crop the images to focus on their main features, defaults to False
+ :type crop_to_features: bool, optional
+ :param correct_rotation: Whether attempt perspective correction by rotating the images, defaults to False
+ :type correct_rotation: bool, optional
+ :return: The list of enhanced images
+ :rtype: XAImageList
- .. versionadded:: 0.0.4
+ .. versionadded:: 0.1.0 """
- self.set_property("text",reversed(self.text))
+ images=self.__partial_init()
+
+ enhanced_images=[None]*images.count()
+ defenhance_image(image,index):
+ ci_image=Quartz.CIImage.imageWithCGImage_(image.CGImage())
+
+ options={
+ Quartz.kCIImageAutoAdjustRedEye:correct_red_eye,
+ Quartz.kCIImageAutoAdjustCrop:crop_to_features,
+ Quartz.kCIImageAutoAdjustLevel:correct_rotation
+ }
+
+ enhancements=ci_image.autoAdjustmentFiltersWithOptions_(options)
+ forfilterinenhancements:
+ filter.setValue_forKey_(ci_image,"inputImage")
+ ci_image=filter.outputImage()
+
+ # Crop the result to the original image size
+ cropped=ci_image.imageByCroppingToRect_(Quartz.CGRectMake(0,0,image.size().width*2,image.size().height*2))
+
+ # Convert back to NSImage
+ rep=AppKit.NSCIImageRep.imageRepWithCIImage_(cropped)
+ result=AppKit.NSImage.alloc().initWithSize_(rep.size())
+ result.addRepresentation_(rep)
+ enhanced_images[index]=result
+
+ threads=[None]*images.count()
+ forindex,imageinenumerate(images):
+ threads[index]=self._spawn_thread(enhance_image,[image,index])
+
+ whileany([t.is_alive()fortinthreads]):
+ time.sleep(0.01)
+
+ self.modified=True
+ self.xa_elem=AppKit.NSMutableArray.alloc().initWithArray_(enhanced_images)returnself
[docs]defrotate(self,degrees:float)->'XAImageList':
+ """Rotates each image in the list by the specified amount of degrees.
- def__repr__(self):
- return"<"+str(type(self))+str(self.xa_elem.get())+">"
+ :param degrees: The number of degrees to rotate the images by
+ :type degrees: float
+ :return: The list of rotated images
+ :rtype: XAImageList
-
[docs]classXAText(XAObject):
- """A class for managing and interacting with the text of documents.
+ .. versionadded:: 0.1.0
+ """
+ sinDegrees=abs(math.sin(degrees*math.pi/180.0))
+ cosDegrees=abs(math.cos(degrees*math.pi/180.0))
- .. versionadded:: 0.0.1
- """
- def__init__(self,properties):
- super().__init__(properties)
+ images=self.__partial_init()
+
+ rotated_images=[None]*images.count()
+ defrotate_image(image,index):
+ new_size=Quartz.CGSizeMake(image.size().height*sinDegrees+image.size().width*cosDegrees,image.size().width*sinDegrees+image.size().height*cosDegrees)
+ rotated_image=AppKit.NSImage.alloc().initWithSize_(new_size)
- self.text:str#: The plaint ext contents of the rich text
- self.color:XAColor#: The color of the first character
- self.font:str#: The name of the font of the first character
- self.size:int#: The size in points of the first character
+ imageBounds=Quartz.CGRectMake((new_size.width-image.size().width)/2,(new_size.height-image.size().height)/2,image.size().width,image.size().height)
- @property
- deftext(self)->str:
- returnself.xa_elem.text()
+ transform=AppKit.NSAffineTransform.alloc().init()
+ transform.translateXBy_yBy_(new_size.width/2,new_size.height/2)
+ transform.rotateByDegrees_(degrees)
+ transform.translateXBy_yBy_(-new_size.width/2,-new_size.height/2)
- @text.setter
- deftext(self,text:str):
- self.set_property("text",text)
+ rotated_image.lockFocus()
+ transform.concat()
+ image.drawInRect_fromRect_operation_fraction_(imageBounds,Quartz.CGRectZero,AppKit.NSCompositingOperationCopy,1.0)
+ rotated_image.unlockFocus()
- @property
- defcolor(self)->'XAColor':
- returnXAColor(self.xa_elem.color())
+ rotated_images[index]=rotated_image
- @color.setter
- defcolor(self,color:'XAColor'):
- self.set_property("color",color.xa_elem)
+ threads=[None]*images.count()
+ forindex,imageinenumerate(images):
+ threads[index]=self._spawn_thread(rotate_image,[image,index])
- @property
- deffont(self)->str:
- returnself.xa_elem.font()
+ whileany([t.is_alive()fortinthreads]):
+ time.sleep(0.01)
- @font.setter
- deffont(self,font:str):
- self.set_property("font",font)
+ self.modified=True
+ self.xa_elem=AppKit.NSMutableArray.alloc().initWithArray_(rotated_images)
+ returnself
[docs]defcrop(self,size:tuple[int,int],corner:Union[tuple[int,int],None]=None)->'XAImageList':
+ """Crops each image in the list to the specified dimensions.
- @size.setter
- defsize(self,size:int):
- self.set_property("size",size)
+ :param size: The dimensions to crop each image to
+ :type size: tuple[int, int]
+ :param corner: The bottom-left location to crom each image from, or None to use (0, 0), defaults to None
+ :type corner: Union[tuple[int, int], None]
+ :return: The list of cropped images
+ :rtype: XAImageList
-
[docs]defscale(self,scale_factor_x:float,scale_factor_y:Union[float,None]=None)->'XAImageList':
+ """Scales each image in the list by the specified horizontal and vertical factors.
- def__str__(self):
- ifisinstance(self.xa_elem,str):
- returnself.xa_elem
- returnstr(self.xa_elem.get())
+ :param scale_factor_x: The factor by which to scale each image in the X dimension
+ :type scale_factor_x: float
+ :param scale_factor_y: The factor by which to scale each image in the Y dimension, or None to match the horizontal factor, defaults to None
+ :type scale_factor_y: Union[float, None]
+ :return: The list of scaled images
+ :rtype: XAImageList
- def__repr__(self):
- ifisinstance(self.xa_elem,str):
- returnself.xa_elem
- returnstr(self.xa_elem.get())
[docs]classXAParagraph(XAText):
- """A class for managing and interacting with paragraphs in text documents.
+ self.modified=True
+ self.xa_elem=AppKit.NSMutableArray.alloc().initWithArray_(scaled_images)
+ returnself
[docs]defpad(self,horizontal_border_width:int=50,vertical_border_width:int=50,pad_color:Union[XAColor,None]=None)->'XAImageList':
+ """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.
+
+ :param horizontal_border_width: The border width, in pixels, in the x-dimension, defaults to 50
+ :type horizontal_border_width: int
+ :param vertical_border_width: The border width, in pixels, in the y-dimension, defaults to 50
+ :type vertical_border_width: int
+ :param pad_color: The color of the border, or None for a white border, defaults to None
+ :type pad_color: Union[XAColor, None]
+ :return: The list of padded images
+ :rtype: XAImageList
+
+ .. versionadded:: 0.1.0
+ """
+ ifpad_colorisNone:
+ # No color provided -- use white by default
+ pad_color=XAColor.white()
+
+ images=self.__partial_init()
+
+ padded_images=[None]*images.count()
+ defpad_image(image,index):
+ new_width=image.size().width+horizontal_border_width*2
+ new_height=image.size().height+vertical_border_width*2
+ color_swatch=pad_color.make_swatch(new_width,new_height)
+
+ color_swatch.xa_elem.lockFocus()
+ bounds=AppKit.NSMakeRect(horizontal_border_width,vertical_border_width,image.size().width,image.size().height)
+ image.drawInRect_(bounds)
+ color_swatch.xa_elem.unlockFocus()
+ padded_images[index]=color_swatch.xa_elem
+
+ threads=[None]*images.count()
+ forindex,imageinenumerate(images):
+ threads[index]=self._spawn_thread(pad_image,[image,index])
+ whileany([t.is_alive()fortinthreads]):
+ time.sleep(0.01)
+ self.modified=True
+ self.xa_elem=AppKit.NSMutableArray.alloc().initWithArray_(padded_images)
+ returnself
-# class XASentenceList(XATextList):
-# """A wrapper around lists of sentences that employs fast enumeration techniques.
+
[docs]defoverlay_image(self,image:'XAImage',location:Union[tuple[int,int],None]=None,size:Union[tuple[int,int],None]=None)->'XAImageList':
+ """Overlays an image on top of each image in the list, at the specified location, with the specified size.
-# .. versionadded:: 0.0.5
-# """
-# def __init__(self, properties: dict, filter: Union[dict, None] = None):
-# super().__init__(properties, XASentence, filter)
+ :param image: The image to overlay on top of each image in the list
+ :type image: XAImage
+ :param location: 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
+ :type location: Union[tuple[int, int], None]
+ :param size: 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
+ :type size: Union[tuple[int, int], None]
+ :return: The list of images with the specified image overlaid on top of them
+ :rtype: XAImageList
+
+ .. versionadded:: 0.1.0
+ """
+ iflocationisNone:
+ # No location provided -- use the bottom-left point of the background image by default
+ location=(0,0)
+
+ images=self.__partial_init()
+ overlayed_images=[None]*images.count()
+ defoverlay_image(img,index,image,size,location):
+ ifsizeisNone:
+ # No dimensions provided -- use size of overlay image by default
+ size=image.size
+ elifsize==(-1,-1):
+ # Use remaining width/height of background image
+ size=(img.size().width-location[0],img.size().height-location[1])
+ elifsize[0]==-1:
+ # Use remaining width of background image + provided height
+ size=(img.size().width-location[0],size[1])
+ elifsize[1]==-1:
+ # Use remaining height of background image + provided width
+ size=(size[1],img.size().width-location[1])
+
+ img.lockFocus()
+ bounds=AppKit.NSMakeRect(location[0],location[1],size[0],size[1])
+ image.xa_elem.drawInRect_(bounds)
+ img.unlockFocus()
+ overlayed_images[index]=img
+
+ threads=[None]*images.count()
+ forindex,imginenumerate(images):
+ threads[index]=self._spawn_thread(overlay_image,[img,index,image,size,location])
-# class XASentence(XAText):
-# """A class for managing and interacting with sentences in text documents.
+ whileany([t.is_alive()fortinthreads]):
+ time.sleep(0.01)
-# .. versionadded:: 0.0.1
-# """
-# def __init__(self, properties):
-# super().__init__(properties)
+ self.modified=True
+ self.xa_elem=AppKit.NSMutableArray.alloc().initWithArray_(overlayed_images)
+ returnself
[docs]defoverlay_text(self,text:str,location:Union[tuple[int,int],None]=None,font_size:float=12,font_color:Union[XAColor,None]=None)->'XAImageList':
+ """Overlays text of the specified size and color at the provided location within each image of the list.
+ :param text: The text to overlay onto each image of the list
+ :type text: str
+ :param location: The bottom-left point of the start of the text, or None to use (5, 5), defaults to None
+ :type location: Union[tuple[int, int], None]
+ :param font_size: The font size, in pixels, of the text, defaults to 12
+ :type font_size: float
+ :param font_color: The color of the text, or None to use black, defaults to None
+ :type font_color: XAColor
+ :return: The list of images with the specified text overlaid on top of them
+ :rtype: XAImageList
+
+ .. versionadded:: 0.1.0
+ """
+ iflocationisNone:
+ # No location provided -- use (5, 5) by default
+ location=(5,5)
+
+ iffont_colorisNone:
+ # No color provided -- use black by default
+ font_color=XAColor.black()
+
+ font=AppKit.NSFont.userFontOfSize_(font_size)
+ images=self.__partial_init()
+ overlayed_images=[None]*self.xa_elem.count()
+ defoverlay_text(image,index):
+ textRect=Quartz.CGRectMake(location[0],0,image.size().width-location[0],location[1])
+ attributes={
+ AppKit.NSFontAttributeName:font,
+ AppKit.NSForegroundColorAttributeName:font_color.xa_elem
+ }
+ image.lockFocus()
+ AppKit.NSString.alloc().initWithString_(text).drawInRect_withAttributes_(textRect,attributes)
+ image.unlockFocus()
+ overlayed_images[index]=image
+ threads=[None]*self.xa_elem.count()
+ forindex,imageinenumerate(images):
+ threads[index]=self._spawn_thread(overlay_text,[image,index])
-
[docs]classXAWordList(XATextList):
- """A wrapper around lists of words that employs fast enumeration techniques.
+ whileany([t.is_alive()fortinthreads]):
+ time.sleep(0.01)
- .. versionadded:: 0.0.5
- """
- def__init__(self,properties:dict,filter:Union[dict,None]=None):
- super().__init__(properties,filter,XAWord)
[docs]classXAWord(XAText):
- """A class for managing and interacting with words in text documents.
+
[docs]defextract_text(self)->list[str]:
+ """Extracts and returns a list of all visible text in each image of the list.
- .. versionadded:: 0.0.1
- """
- def__init__(self,properties):
- super().__init__(properties)
[docs]classXACharacterList(XATextList):
- """A wrapper around lists of characters that employs fast enumeration techniques.
+
[docs]defshow_in_preview(self):
+ """Opens each image in the list in Preview.
- .. versionadded:: 0.0.5
- """
- def__init__(self,properties:dict,filter:Union[dict,None]=None):
- super().__init__(properties,filter,XACharacter)
[docs]defsave(self,file_paths:list[Union[XAPath,str]]):
+ """Saves each image to a file on the disk.
+
+ :param file_path: The path at which to save the image file. Any existing file at that location will be overwritten, defaults to None
+ :type file_path: Union[XAPath, str, None]
+
+ .. versionadded:: 0.1.0
+ """
+ forindex,imageinenumerate(self):
+ path=None
+ iflen(file_paths)>index:
+ path=file_paths[index]
+ image.save(path)
+
+
[docs]defget_clipboard_representation(self)->list[AppKit.NSImage]:
+ """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
+
+ :return: A list of media item file URLs
+ :rtype: list[NSURL]
+
+ .. versionadded:: 0.0.8
+ """
+ data=[]
+ forimageinself.__partial_init():
+ ifimage.TIFFRepresentation():
+ data.append(image)
+ returndata
-
[docs]classXACharacter(XAText):
- """A class for managing and interacting with characters in text documents.
+
+ def__init__(self,image_reference:Union[str,XAPath,AppKit.NSURL,AppKit.NSImage,None]=None,data:Union[AppKit.NSData,None]=None):
+ self.size:tuple[int,int]#: The dimensions of the image
+ self.file:Union[XAPath,None]=None#: The path to the image file, if one exists
+ self.data:str#: The TIFF representation of the image
+ self.modified:bool=False#: Whether the image data has been modified since the object was originally created
+ self.xa_elem=None
+ self.__vibrance=None
+ self.__gamma=None
+ self.__tint=None
+ self.__temperature=None
+ self.__white_point=None
+ self.__highlight=None
+ self.__shadow=None
-
[docs]classXAAttributeRunList(XATextList):
- """A wrapper around lists of attribute runs that employs fast enumeration techniques.
+ ifdataisnotNone:
+ # Deprecated as of 0.1.0 -- Pass data as the image_reference instead
+ logging.warning("Setting the data parameter when initalizing an XAImage is deprecated functionality and will be removed in a future release")
+ self.xa_elem=AppKit.NSImage.alloc().initWithData_(data)
+ else:
+ self.file=image_reference
+ matchimage_reference:
+ caseNone:
+ logging.debug("Image ref is none -- use empty NSImage")
+ self.xa_elem=AppKit.NSImage.alloc().init()
+
+ case{"element":str(ref)}:
+ logging.debug("Image ref is string from XAList --> Reinit XAImage with string")
+ self.file=ref
+ self.xa_elem=XAImage(ref).xa_elem
+
+ case{"element":XAImage()asimage}:
+ logging.debug("Image ref is XAImage from XAList --> Set xa_elem to that image's xa_elem")
+ self.file=image.file
+ self.xa_elem=image.xa_elem
+
+ case{"element":AppKit.NSImage()asimage}:
+ logging.debug("Image ref is NSImage from XAList --> Set xa_elem to that image")
+ self.xa_elem=image
+
+ casestr()asrefif"://"inref:
+ logging.debug("Image ref is web/file URL string --> Init NSImage with URL")
+ url=XAURL(ref).xa_elem
+ self.xa_elem=AppKit.NSImage.alloc().initWithContentsOfURL_(url)
+
+ casestr()asrefifos.path.exists(ref)oros.path.exists(os.getcwd()+"/"+ref):
+ logging.debug("Image ref is file path string --> Init NSImage with path URL")
+ path=XAPath(ref).xa_elem
+ self.xa_elem=AppKit.NSImage.alloc().initWithContentsOfURL_(path)
+
+ caseXAPath()aspath:
+ logging.debug("Image ref is file path object --> Init NSImage with path URL")
+ self.file=path.path
+ self.xa_elem=AppKit.NSImage.alloc().initWithContentsOfURL_(path.xa_elem)
+
+ caseXAURL()asurl:
+ logging.debug("Image ref is web/file URL object --> Init NSImage with URL")
+ self.file=url.url
+ self.xa_elem=AppKit.NSImage.alloc().initWithContentsOfURL_(url.xa_elem)
+
+ casestr()asraw_string:
+ logging.debug("Image ref is raw string --> Make image from string")
+ font=AppKit.NSFont.monospacedSystemFontOfSize_weight_(15,AppKit.NSFontWeightMedium)
+ text=AppKit.NSString.alloc().initWithString_(raw_string)
+ attributes={
+ AppKit.NSFontAttributeName:font,
+ AppKit.NSForegroundColorAttributeName:XAColor.black().xa_elem
+ }
+ text_size=text.sizeWithAttributes_(attributes)
+
+ # Make a white background to overlay the text on
+ swatch=XAColor.white().make_swatch(text_size.width+20,text_size.height+20)
+ text_rect=AppKit.NSMakeRect(10,10,text_size.width,text_size.height)
+
+ # Overlay the text
+ swatch.xa_elem.lockFocus()
+ text.drawInRect_withAttributes_(text_rect,attributes)
+ swatch.xa_elem.unlockFocus()
+ self.xa_elem=swatch.xa_elem
+
+ caseXAImage()asimage:
+ self.file=image.file
+ self.xa_elem=image.xa_elem
+
+ caseXAObject():
+ logging.debug("Image ref is XAObject --> Obtain proper ref via XAImageLike protocol")
+ self.xa_elem=XAImage(image_reference.get_image_representation()).xa_elem
+
+ caseAppKit.NSData()asdata:
+ logging.debug("Image ref is NSData --> Init NSImage with data")
+ self.xa_elem=AppKit.NSImage.alloc().initWithData_(data)
+
+ caseAppKit.NSImage()asimage:
+ logging.debug("Image ref is NSImage --> Set xa_elem to that image")
+ self.xa_elem=image
+
+ case_:
+ logging.debug(f"Image ref is of unaccounted for type {type(image_reference)} --> Raise TypeError")
+ raiseTypeError(f"Error: Cannot initialize XAImage using {type(image_reference)} type.")
+
+ def__update_image(self,modified_image:Quartz.CIImage)->'XAImage':
+ # Crop the result to the original image size
+ cropped=modified_image.imageByCroppingToRect_(Quartz.CGRectMake(0,0,self.size[0]*2,self.size[1]*2))
+
+ # Convert back to NSImage
+ rep=AppKit.NSCIImageRep.imageRepWithCIImage_(cropped)
+ result=AppKit.NSImage.alloc().initWithSize_(rep.size())
+ result.addRepresentation_(rep)
+
+ # Update internal data
+ self.xa_elem=result
+ self.modified=True
+ returnself
- .. versionadded:: 0.0.5
- """
- def__init__(self,properties:dict,filter:Union[dict,None]=None):
- super().__init__(properties,filter,XAAttributeRun)
+ @property
+ defsize(self)->tuple[int,int]:
+ """The dimensions of the image, in pixels.
-
[docs]classXAAttributeRun(XAText):
- """A class for managing and interacting with attribute runs in text documents.
+ .. versionadded:: 0.1.0
+ """
+ returntuple(self.xa_elem.size())
- .. versionadded:: 0.0.1
- """
- def__init__(self,properties):
- super().__init__(properties)
+ @property
+ defdata(self)->AppKit.NSData:
+ returnself.xa_elem.TIFFRepresentation()
+ @property
+ defhas_alpha_channel(self)->bool:
+ """Whether the image has an alpha channel or not.
+ .. versionadded:: 0.1.0
+ """
+ reps=self.xa_elem.representations()
+ iflen(reps)>0:
+ returnreps[0].hasAlpha()
+ # TODO: Make sure this is never a false negative
+ returnFalse
+ @property
+ defis_opaque(self)->bool:
+ """Whether the image contains transparent pixels or not.
-
[docs]classXAAttachmentList(XATextList):
- """A wrapper around lists of text attachments that employs fast enumeration techniques.
+ .. versionadded:: 0.1.0
+ """
+ reps=self.xa_elem.representations()
+ iflen(reps)>0:
+ returnreps[0].isOpaque()
+ # TODO: Make sure this is never a false negative
+ returnFalse
- .. versionadded:: 0.0.5
- """
- def__init__(self,properties:dict,filter:Union[dict,None]=None):
- super().__init__(properties,filter,XAAttachment)
+ @property
+ defcolor_space_name(self)->Union[str,None]:
+ """The name of the color space that the image currently uses.
-
[docs]classXAAttachment(XAObject):
- """A class for managing and interacting with attachments in text documents.
+ .. versionadded:: 0.1.0
+ """
+ reps=self.xa_elem.representations()
+ iflen(reps)>0:
+ returnreps[0].colorSpaceName()
+ # TODO: Make sure this is never a false negative
+ returnNone
- .. versionadded:: 0.0.1
- """
- def__init__(self,properties):
- super().__init__(properties)
+ @property
+ defgamma(self)->float:
+ """The gamma value for the image, once it has been manually set. Otherwise, the value is None.
+
+ .. versionadded:: 0.1.0
+ """
+ ifself.__gammaisnotNone:
+ returnself.__gamma
+ return-1
+
+ @gamma.setter
+ defgamma(self,gamma:float):
+ self.__gamma=gamma
+ image=Quartz.CIImage.imageWithData_(self.data)
+ filter=Quartz.CIFilter.filterWithName_("CIGammaAdjust")
+ filter.setDefaults()
+ filter.setValue_forKey_(image,"inputImage")
+ filter.setValue_forKey_(gamma,"inputPower")
+ uncropped=filter.valueForKey_(Quartz.kCIOutputImageKey)
+ self.__update_image(uncropped)
+
+ @property
+ defvibrance(self)->Union[float,None]:
+ """The vibrance value for the image, once it has been manually set. Otherwise, the value is None.
+
+ .. versionadded:: 0.1.0
+ """
+ ifself.__vibranceisnotNone:
+ returnself.__vibrance
+ return-1
+
+ @vibrance.setter
+ defvibrance(self,vibrance:float=1):
+ self.__vibrance=vibrance
+ image=Quartz.CIImage.imageWithData_(self.data)
+ filter=Quartz.CIFilter.filterWithName_("CIVibrance")
+ filter.setDefaults()
+ filter.setValue_forKey_(image,"inputImage")
+ filter.setValue_forKey_(vibrance,"inputAmount")
+ uncropped=filter.valueForKey_(Quartz.kCIOutputImageKey)
+ returnself.__update_image(uncropped)
+ @property
+ deftint(self)->Union[float,None]:
+ """The tint setting for the image, once it has been manually set. Otherwise, the value is None.
+
+ .. versionadded:: 0.1.0
+ """
+ ifself.__tintisnotNone:
+ returnself.__tint
+ return-1
+
+ @tint.setter
+ deftint(self,tint:float):
+ # -100 to 100
+ temp_and_tint=Quartz.CIVector.vectorWithX_Y_(6500,tint)
+ self.__tint=tint
+ image=Quartz.CIImage.imageWithData_(self.data)
+ filter=Quartz.CIFilter.filterWithName_("CITemperatureAndTint")
+ filter.setDefaults()
+ filter.setValue_forKey_(image,"inputImage")
+ filter.setValue_forKey_(temp_and_tint,"inputTargetNeutral")
+ uncropped=filter.valueForKey_(Quartz.kCIOutputImageKey)
+ self.__update_image(uncropped)
+ @property
+ deftemperature(self)->Union[float,None]:
+ """The temperature setting for the image, once it has been manually set. Otherwise, the value is None.
+
+ .. versionadded:: 0.1.0
+ """
+ ifself.__temperatureisnotNone:
+ returnself.__temperature
+ return-1
+
+ @temperature.setter
+ deftemperature(self,temperature:float):
+ # 2000 to inf
+ temp_and_tint=Quartz.CIVector.vectorWithX_Y_(temperature,0)
+ self.__temperature=temperature
+ image=Quartz.CIImage.imageWithData_(self.data)
+ filter=Quartz.CIFilter.filterWithName_("CITemperatureAndTint")
+ filter.setDefaults()
+ filter.setValue_forKey_(image,"inputImage")
+ filter.setValue_forKey_(temp_and_tint,"inputTargetNeutral")
+ uncropped=filter.valueForKey_(Quartz.kCIOutputImageKey)
+ self.__update_image(uncropped)
-
[docs]classXAColorList(XATextList):
- """A wrapper around lists of colors that employs fast enumeration techniques.
+ @property
+ defwhite_point(self)->Union['XAColor',None]:
+ """The white point setting for the image, once it has been manually set. Otherwise, the value is None.
+
+ .. versionadded:: 0.1.0
+ """
+ ifself.__white_pointisnotNone:
+ returnself.__white_point
+ return-1
+
+ @white_point.setter
+ defwhite_point(self,white_point:XAColor):
+ self.__white_point=white_point
+ ci_white_point=Quartz.CIColor.alloc().initWithColor_(white_point.xa_elem)
+ image=Quartz.CIImage.imageWithData_(self.data)
+ filter=Quartz.CIFilter.filterWithName_("CIWhitePointAdjust")
+ filter.setDefaults()
+ filter.setValue_forKey_(image,"inputImage")
+ filter.setValue_forKey_(ci_white_point,"inputColor")
+ uncropped=filter.valueForKey_(Quartz.kCIOutputImageKey)
+ self.__update_image(uncropped)
- .. versionadded:: 0.0.6
- """
- def__init__(self,properties:dict,filter:Union[dict,None]=None):
- super().__init__(properties,XAColor,filter)
+ @property
+ defhighlight(self)->float:
+ """The highlight setting for the image, once it has been manually set. Otherwise, the value is None.
+
+ .. versionadded:: 0.1.0
+ """
+ ifself.__highlightisnotNone:
+ returnself.__highlight
+ return-1
+
+ @highlight.setter
+ defhighlight(self,highlight:float):
+ self.__highlight=highlight
+ image=Quartz.CIImage.imageWithData_(self.data)
+ filter=Quartz.CIFilter.filterWithName_("CIHighlightShadowAdjust")
+ filter.setDefaults()
+ filter.setValue_forKey_(image,"inputImage")
+ filter.setValue_forKey_(highlight,"inputHighlightAmount")
+ uncropped=filter.valueForKey_(Quartz.kCIOutputImageKey)
+ self.__update_image(uncropped)
-
[docs]classXAColor(XAObject):
- def__init__(self,*args):
- iflen(args)==1:
- self.copy_color(args[0])
+ @property
+ defshadow(self)->float:
+ """The shadow setting for the image, once it has been manually set. Otherwise, the value is None.
+
+ .. versionadded:: 0.1.0
+ """
+ ifself.__shadowisnotNone:
+ returnself.__shadow
+ return-1
+
+ @shadow.setter
+ defshadow(self,shadow:float):
+ self.__shadow=shadow
+ image=Quartz.CIImage.imageWithData_(self.data)
+ filter=Quartz.CIFilter.filterWithName_("CIHighlightShadowAdjust")
+ filter.setDefaults()
+ filter.setValue_forKey_(image,"inputImage")
+ filter.setValue_forKey_(self.__highlightor1,"inputHighlightAmount")
+ filter.setValue_forKey_(shadow,"inputShadowAmount")
+ uncropped=filter.valueForKey_(Quartz.kCIOutputImageKey)
+ self.__update_image(uncropped)
+
+
[docs]defopen(*images:Union[str,XAPath,list[Union[str,XAPath]]])->Union['XAImage',XAImageList]:
+ """Initializes one or more images from files.
+
+ :param images: The image(s) to open
+ :type images: Union[str, XAPath, list[Union[str, XAPath]]]
+ :return: The newly created image object, or a list of image objects
+ :rtype: Union[XAImage, XAImageList]
+
+ .. versionadded:: 0.1.0
+ """
+ iflen(images)==1:
+ images=images[0]
+
+ ifisinstance(images,list)orisinstance(images,tuple):
+ returnXAImageList({"element":images})else:
- red=args[0]iflen(args)>=0else255
- green=args[1]iflen(args)>=1else255
- blue=args[2]iflen(args)>=3else255
- alpha=args[3]iflen(args)==4else1.0
- self.xa_elem=AppKit.NSCalibratedRGBColor.alloc().initWithRed_green_blue_alpha_(red,green,blue,alpha)
+ returnXAImage(images)
[docs]@staticmethod
+ defimage_from_text(text:str,font_size:int=15,font_name:str="Menlo",font_color:XAColor=XAColor.black(),background_color:XAColor=XAColor.white(),inset:int=10)->'XAImage':
+ """Initializes an image of the provided text overlaid on the specified background color.
+
+ :param text: The text to create an image of
+ :type text: str
+ :param font_size: The font size of the text, defaults to 15
+ :type font_size: int, optional
+ :param font_name: The color of the text, defaults to XAColor.black()
+ :type font_name: str, optional
+ :param font_color: The name of the font to use for the text, defaults to ".SF NS Mono Light Medium"
+ :type font_color: XAColor, optional
+ :param background_color: The color to overlay the text on top of, defaults to XAColor.white()
+ :type background_color: XAColor, optional
+ :param inset: The width of the space between the text and the edge of the background color in the resulting image, defaults to 10
+ :type inset: int, optional
+ :return: XAImage
+ :rtype: The resulting image object
+
+ .. versionadded:: 0.1.0
+ """
+ font=AppKit.NSFont.fontWithName_size_(font_name,font_size)
+ print(font.displayName())
+ text=AppKit.NSString.alloc().initWithString_(text)
+ attributes={
+ AppKit.NSFontAttributeName:font,
+ AppKit.NSForegroundColorAttributeName:font_color.xa_elem
+ }
+ text_size=text.sizeWithAttributes_(attributes)
+
+ # Make a white background to overlay the text on
+ swatch=background_color.make_swatch(text_size.width+inset*2,text_size.height+inset*2)
+ text_rect=AppKit.NSMakeRect(inset,inset,text_size.width,text_size.height)
+
+ # Overlay the text
+ swatch.xa_elem.lockFocus()
+ text.drawInRect_withAttributes_(text_rect,attributes)
+ swatch.xa_elem.unlockFocus()
+ returnswatch
[docs]defedges(self,intensity:float=1.0)->'XAImage':
+ """Detects the edges in the image and highlights them colorfully, blackening other areas of the image.
+
+ :param intensity: The degree to which edges are highlighted. Higher is brighter. Defaults to 1.0
+ :type intensity: float
+ :return: The resulting image after applying the filter
+ :rtype: XAImage
+
+ .. versionadded:: 0.1.0
+ """
+ image=Quartz.CIImage.imageWithData_(self.data)
+ filter=Quartz.CIFilter.filterWithName_("CIEdges")
+ filter.setDefaults()
+ filter.setValue_forKey_(image,"inputImage")
+ filter.setValue_forKey_(intensity,"inputIntensity")
+ uncropped=filter.valueForKey_(Quartz.kCIOutputImageKey)
+ returnself.__update_image(uncropped)
+
+
[docs]defgaussian_blur(self,intensity:float=10)->'XAImage':
+ """Blurs the image using a Gaussian filter.
+
+ :param intensity: The strength of the blur effect, defaults to 10
+ :type intensity: float
+ :return: The resulting image after applying the filter
+ :rtype: XAImage
+
+ .. versionadded:: 0.1.0
+ """
+ image=Quartz.CIImage.imageWithData_(self.data)
+ filter=Quartz.CIFilter.filterWithName_("CIGaussianBlur")
+ filter.setDefaults()
+ filter.setValue_forKey_(image,"inputImage")
+ filter.setValue_forKey_(intensity,"inputRadius")
+ uncropped=filter.valueForKey_(Quartz.kCIOutputImageKey)
+ returnself.__update_image(uncropped)
+
+
[docs]defreduce_noise(self,noise_level:float=0.02,sharpness:float=0.4)->'XAImage':
+ """Reduces noise in the image by sharpening areas with a luminance delta below the specified noise level threshold.
+
+ :param noise_level: The threshold for luminance changes in an area below which will be considered noise, defaults to 0.02
+ :type noise_level: float
+ :param sharpness: The sharpness of the resulting image, defaults to 0.4
+ :type sharpness: float
+ :return: The resulting image after applying the filter
+ :rtype: XAImage
+
+ .. versionadded:: 0.1.0
+ """
+ image=Quartz.CIImage.imageWithData_(self.data)
+ filter=Quartz.CIFilter.filterWithName_("CINoiseReduction")
+ filter.setDefaults()
+ filter.setValue_forKey_(image,"inputImage")
+ filter.setValue_forKey_(noise_level,"inputNoiseLevel")
+ filter.setValue_forKey_(sharpness,"inputSharpness")
+ uncropped=filter.valueForKey_(Quartz.kCIOutputImageKey)
+ returnself.__update_image(uncropped)
+
+
[docs]defpixellate(self,pixel_size:float=8.0)->'XAImage':
+ """Pixellates the image.
+
+ :param pixel_size: The size of the pixels, defaults to 8.0
+ :type pixel_size: float
+ :return: The resulting image after applying the filter
+ :rtype: XAImage
+
+ .. versionadded:: 0.1.0
+ """
+ image=Quartz.CIImage.imageWithData_(self.data)
+ filter=Quartz.CIFilter.filterWithName_("CIPixellate")
+ filter.setDefaults()
+ filter.setValue_forKey_(image,"inputImage")
+ filter.setValue_forKey_(pixel_size,"inputScale")
+ uncropped=filter.valueForKey_(Quartz.kCIOutputImageKey)
+ returnself.__update_image(uncropped)
+
+
[docs]defoutline(self,threshold:float=0.1)->'XAImage':
+ """Outlines detected edges within the image in black, leaving the rest transparent.
+
+ :param threshold: The threshold to use when separating edge and non-edge pixels. Larger values produce thinner edge lines. Defaults to 0.1
+ :type threshold: float
+ :return: The resulting image after applying the filter
+ :rtype: XAImage
+
+ .. versionadded:: 0.1.0
+ """
+ image=Quartz.CIImage.imageWithData_(self.data)
+ filter=Quartz.CIFilter.filterWithName_("CILineOverlay")
+ filter.setDefaults()
+ filter.setValue_forKey_(image,"inputImage")
+ filter.setValue_forKey_(threshold,"inputThreshold")
+ uncropped=filter.valueForKey_(Quartz.kCIOutputImageKey)
+ returnself.__update_image(uncropped)
+
+
[docs]definvert(self)->'XAImage':
+ """Inverts the color of the image.
+
+ :return: The resulting image after applying the filter
+ :rtype: XAImage
+
+ .. versionadded:: 0.1.0
+ """
+ image=Quartz.CIImage.imageWithData_(self.data)
+ filter=Quartz.CIFilter.filterWithName_("CIColorInvert")
+ filter.setDefaults()
+ filter.setValue_forKey_(image,"inputImage")
+ uncropped=filter.valueForKey_(Quartz.kCIOutputImageKey)
+ returnself.__update_image(uncropped)
+
+
[docs]defsepia(self,intensity:float=1.0)->'XAImage':
+ """Applies a sepia filter to the image; maps all colors of the image to shades of brown.
+
+ :param intensity: The opacity of the sepia effect. A value of 0 will have no impact on the image. Defaults to 1.0
+ :type intensity: float
+ :return: The resulting image after applying the filter
+ :rtype: XAImage
+
+ .. versionadded:: 0.1.0
+ """
+ image=Quartz.CIImage.imageWithData_(self.data)
+ filter=Quartz.CIFilter.filterWithName_("CISepiaTone")
+ filter.setDefaults()
+ filter.setValue_forKey_(image,"inputImage")
+ filter.setValue_forKey_(intensity,"inputIntensity")
+ uncropped=filter.valueForKey_(Quartz.kCIOutputImageKey)
+ returnself.__update_image(uncropped)
+
+
[docs]defvignette(self,intensity:float=1.0)->'XAImage':
+ """Applies vignette shading to the corners of the image.
+
+ :param intensity: The intensity of the vignette effect, defaults to 1.0
+ :type intensity: float
+ :return: The resulting image after applying the filter
+ :rtype: XAImage
+
+ .. versionadded:: 0.1.0
+ """
+ image=Quartz.CIImage.imageWithData_(self.data)
+ filter=Quartz.CIFilter.filterWithName_("CIVignette")
+ filter.setDefaults()
+ filter.setValue_forKey_(image,"inputImage")
+ filter.setValue_forKey_(intensity,"inputIntensity")
+ uncropped=filter.valueForKey_(Quartz.kCIOutputImageKey)
+ returnself.__update_image(uncropped)
+
+
[docs]defdepth_of_field(self,focal_region:Union[tuple[tuple[int,int],tuple[int,int]],None]=None,intensity:float=10.0,focal_region_saturation:float=1.5)->'XAImage':
+ """Applies a depth of field filter to the image, simulating a tilt & shift effect.
+
+ :param focal_region: 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
+ :type focal_region: Union[tuple[tuple[int, int], tuple[int, int]], None]
+ :param intensity: 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
+ :type intensity: float
+ :param focal_region_saturation: Adjusts the saturation of the focial region. Higher values increase saturation. Defaults to 1.5 (1.5x default saturation)
+ :type focal_region_saturation: float
+ :return: The resulting image after applying the filter
+ :rtype: XAImage
+
+ .. versionadded:: 0.1.0
+ """
+ iffocal_regionisNone:
+ center_top=Quartz.CIVector.vectorWithX_Y_(self.size[0]/2,self.size[1]/3)
+ center_bottom=Quartz.CIVector.vectorWithX_Y_(self.size[0]/2,self.size[1]/3*2)
+ focal_region=(center_top,center_bottom)
+ else:
+ point1=Quartz.CIVector.vectorWithX_Y_(focal_region[0])
+ point2=Quartz.CIVector.vectorWithX_Y_(focal_region[1])
+ focal_region=(point1,point2)
+
+ image=Quartz.CIImage.imageWithData_(self.data)
+ filter=Quartz.CIFilter.filterWithName_("CIDepthOfField")
+ filter.setDefaults()
+ filter.setValue_forKey_(image,"inputImage")
+ filter.setValue_forKey_(focal_region[0],"inputPoint0")
+ filter.setValue_forKey_(focal_region[1],"inputPoint1")
+ filter.setValue_forKey_(intensity,"inputRadius")
+ filter.setValue_forKey_(focal_region_saturation,"inputSaturation")
+ uncropped=filter.valueForKey_(Quartz.kCIOutputImageKey)
+ returnself.__update_image(uncropped)
+
+
[docs]defcrystallize(self,crystal_size:float=20.0)->'XAImage':
+ """Applies a crystallization filter to the image. Creates polygon-shaped color blocks by aggregating pixel values.
+
+ :param crystal_size: The radius of the crystals, defaults to 20.0
+ :type crystal_size: float
+ :return: The resulting image after applying the filter
+ :rtype: XAImage
+
+ .. versionadded:: 0.1.0
+ """
+ image=Quartz.CIImage.imageWithData_(self.data)
+ filter=Quartz.CIFilter.filterWithName_("CICrystallize")
+ filter.setDefaults()
+ filter.setValue_forKey_(image,"inputImage")
+ filter.setValue_forKey_(crystal_size,"inputRadius")
+ uncropped=filter.valueForKey_(Quartz.kCIOutputImageKey)
+ returnself.__update_image(uncropped)
+
+
[docs]defcomic(self)->'XAImage':
+ """Applies a comic filter to the image. Outlines edges and applies a color halftone effect.
+
+ :return: The resulting image after applying the filter
+ :rtype: XAImage
+
+ .. versionadded:: 0.1.0
+ """
+ image=Quartz.CIImage.imageWithData_(self.data)
+ filter=Quartz.CIFilter.filterWithName_("CIComicEffect")
+ filter.setDefaults()
+ filter.setValue_forKey_(image,"inputImage")
+ uncropped=filter.valueForKey_(Quartz.kCIOutputImageKey)
+ returnself.__update_image(uncropped)
+
+
[docs]defpointillize(self,point_size:float=20.0)->'XAImage':
+ """Applies a pointillization filter to the image.
+
+ :param crystal_size: The radius of the points, defaults to 20.0
+ :type crystal_size: float
+ :return: The resulting image after applying the filter
+ :rtype: XAImage
+
+ .. versionadded:: 0.1.0
+ """
+ image=Quartz.CIImage.imageWithData_(self.data)
+ filter=Quartz.CIFilter.filterWithName_("CIPointillize")
+ filter.setDefaults()
+ filter.setValue_forKey_(image,"inputImage")
+ filter.setValue_forKey_(point_size,"inputRadius")
+ uncropped=filter.valueForKey_(Quartz.kCIOutputImageKey)
+ returnself.__update_image(uncropped)
+
+
[docs]defbloom(self,intensity:float=0.5)->'XAImage':
+ """Applies a bloom effect to the image. Softens edges and adds a glow.
+
+ :param intensity: The strength of the softening and glow effects, defaults to 0.5
+ :type intensity: float
+ :return: The resulting image after applying the filter
+ :rtype: XAImage
+
+ .. versionadded:: 0.1.0
+ """
+ image=Quartz.CIImage.imageWithData_(self.data)
+ filter=Quartz.CIFilter.filterWithName_("CIBloom")
+ filter.setDefaults()
+ filter.setValue_forKey_(image,"inputImage")
+ filter.setValue_forKey_(intensity,"inputIntensity")
+ uncropped=filter.valueForKey_(Quartz.kCIOutputImageKey)
+ returnself.__update_image(uncropped)
+
+
[docs]defmonochrome(self,color:XAColor,intensity:float=1.0)->'XAImage':
+ """Remaps the colors of the image to shades of the specified color.
+
+ :param color: The color of map the image's colors to
+ :type color: XAColor
+ :param intensity: The strength of recoloring effect. Higher values map colors to darker shades of the provided color. Defaults to 1.0
+ :type intensity: float
+ :return: The resulting image after applying the filter
+ :rtype: XAImage
+
+ .. versionadded:: 0.1.0
+ """
+ ci_color=Quartz.CIColor.alloc().initWithColor_(color.xa_elem)
+ image=Quartz.CIImage.imageWithData_(self.data)
+ filter=Quartz.CIFilter.filterWithName_("CIColorMonochrome")
+ filter.setDefaults()
+ filter.setValue_forKey_(image,"inputImage")
+ filter.setValue_forKey_(ci_color,"inputColor")
+ filter.setValue_forKey_(intensity,"inputIntensity")
+ uncropped=filter.valueForKey_(Quartz.kCIOutputImageKey)
+ returnself.__update_image(uncropped)
+
+
[docs]defbump(self,center:Union[tuple[int,int],None]=None,radius:float=300.0,curvature:float=0.5)->'XAImage':
+ """Creates a concave (inward) or convex (outward) bump at the specified location within the image.
+
+ :param center: The center point of the effect, or None to use the center of the image, defaults to None
+ :type center: Union[tuple[int, int], None]
+ :param radius: The radius of the bump in pixels, defaults to 300.0
+ :type radius: float
+ :param curvature: 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
+ :type curvature: float
+ :return: The resulting image after applying the distortion
+ :rtype: XAImage
+
+ .. versionadded:: 0.1.0
+ """
+ ifcenterisNone:
+ center=Quartz.CIVector.vectorWithX_Y_(self.size[0]/2,self.size[1]/2)
+ else:
+ center=Quartz.CIVector.vectorWithX_Y_(center[0],center[1])
+
+ image=Quartz.CIImage.imageWithData_(self.data)
+ filter=Quartz.CIFilter.filterWithName_("CIBumpDistortion")
+ filter.setDefaults()
+ filter.setValue_forKey_(image,"inputImage")
+ filter.setValue_forKey_(center,"inputCenter")
+ filter.setValue_forKey_(radius,"inputRadius")
+ filter.setValue_forKey_(curvature,"inputScale")
+ uncropped=filter.valueForKey_(Quartz.kCIOutputImageKey)
+ returnself.__update_image(uncropped)
+
+
[docs]defpinch(self,center:Union[tuple[int,int],None]=None,intensity:float=0.5)->'XAImage':
+ """Creates an inward pinch distortion at the specified location within the image.
+
+ :param center: The center point of the effect, or None to use the center of the image, defaults to None
+ :type center: Union[tuple[int, int], None]
+ :param intensity: Controls the scale of the pinch effect. Higher values stretch pixels away from the specified center to a greater degree. Defaults to 0.5
+ :type intensity: float
+ :return: The resulting image after applying the distortion
+ :rtype: XAImage
+
+ .. versionadded:: 0.1.0
+ """
+ ifcenterisNone:
+ center=Quartz.CIVector.vectorWithX_Y_(self.size[0]/2,self.size[1]/2)
+ else:
+ center=Quartz.CIVector.vectorWithX_Y_(center[0],center[1])
+
+ image=Quartz.CIImage.imageWithData_(self.data)
+ filter=Quartz.CIFilter.filterWithName_("CIPinchDistortion")
+ filter.setDefaults()
+ filter.setValue_forKey_(image,"inputImage")
+ filter.setValue_forKey_(center,"inputCenter")
+ filter.setValue_forKey_(intensity,"inputScale")
+ uncropped=filter.valueForKey_(Quartz.kCIOutputImageKey)
+ returnself.__update_image(uncropped)
+
+
[docs]deftwirl(self,center:Union[tuple[int,int],None]=None,radius:float=300.0,angle:float=3.14)->'XAImage':
+ """Creates a twirl distortion by rotating pixels around the specified location within the image.
+
+ :param center: The center point of the effect, or None to use the center of the image, defaults to None
+ :type center: Union[tuple[int, int], None]
+ :param radius: The pixel radius around the centerpoint that defines the area to apply the effect to, defaults to 300.0
+ :type radius: float
+ :param angle: The angle of the twirl in radians, defaults to 3.14
+ :type angle: float
+ :return: The resulting image after applying the distortion
+ :rtype: XAImage
+
+ .. versionadded:: 0.1.0
+ """
+ ifcenterisNone:
+ center=Quartz.CIVector.vectorWithX_Y_(self.size[0]/2,self.size[1]/2)
+ else:
+ center=Quartz.CIVector.vectorWithX_Y_(center[0],center[1])
+
+ image=Quartz.CIImage.imageWithData_(self.data)
+ filter=Quartz.CIFilter.filterWithName_("CITwirlDistortion")
+ filter.setDefaults()
+ filter.setValue_forKey_(image,"inputImage")
+ filter.setValue_forKey_(center,"inputCenter")
+ filter.setValue_forKey_(radius,"inputRadius")
+ filter.setValue_forKey_(angle,"inputAngle")
+ uncropped=filter.valueForKey_(Quartz.kCIOutputImageKey)
+ returnself.__update_image(uncropped)
+
+
[docs]defauto_enhance(self,correct_red_eye:bool=False,crop_to_features:bool=False,correct_rotation:bool=False)->'XAImage':
+ """Attempts to enhance the image by applying suggested filters.
+
+ :param correct_red_eye: Whether to attempt red eye removal, defaults to False
+ :type correct_red_eye: bool, optional
+ :param crop_to_features: Whether to crop the image to focus on the main features with it, defaults to False
+ :type crop_to_features: bool, optional
+ :param correct_rotation: Whether attempt perspective correction by rotating the image, defaults to False
+ :type correct_rotation: bool, optional
+ :return: The resulting image after applying the enchantments
+ :rtype: XAImage
+
+ .. versionadded:: 0.1.0
+ """
+ ci_image=Quartz.CIImage.imageWithData_(self.data)
+ options={
+ Quartz.kCIImageAutoAdjustRedEye:correct_red_eye,
+ Quartz.kCIImageAutoAdjustCrop:crop_to_features,
+ Quartz.kCIImageAutoAdjustLevel:correct_rotation
+ }
+ enhancements=ci_image.autoAdjustmentFiltersWithOptions_(options)
+ print(enhancements)
+ forfilterinenhancements:
+ filter.setValue_forKey_(ci_image,"inputImage")
+ ci_image=filter.outputImage()
+ returnself.__update_image(ci_image)
+ :param degrees: The number of degrees to rotate the image by
+ :type degrees: float
+ :return: The image object, modifications included
+ :rtype: XAImage
-
[docs]defcrop(self,size:tuple[int,int],corner:Union[tuple[int,int],None]=None)->'XAImage':
+ """Crops the image to the specified dimensions.
+ :param size: The width and height of the resulting image
+ :type size: tuple[int, int]
+ :param corner: The bottom-left corner location from which to crop the image, or None to use (0, 0), defaults to None
+ :type corner: Union[tuple[int, int], None]
+ :return: The image object, modifications included
+ :rtype: XAImage
+ .. versionadded:: 0.1.0
+ """
+ ifcornerisNone:
+ # No corner provided -- use (0,0) by default
+ corner=(0,0)
+ cropped_image=AppKit.NSImage.alloc().initWithSize_(AppKit.NSMakeSize(size[0],size[1]))
+ imageBounds=AppKit.NSMakeRect(corner[0],corner[1],self.size[0],self.size[1])
-
[docs]classXAImageList(XAList):
- """A wrapper around lists of images that employs fast enumeration techniques.
+ cropped_image.lockFocus()
+ self.xa_elem.drawInRect_(imageBounds)
+ cropped_image.unlockFocus()
+ self.xa_elem=cropped_image
+ self.modified=True
+ returnself
[docs]defscale(self,scale_factor_x:float,scale_factor_y:Union[float,None]=None)->'XAImage':
+ """Scales the image by the specified horizontal and vertical factors.
-
[docs]classXAImage(XAObject,XAClipboardCodable):
- """A wrapper around NSImage with specialized automation methods.
+ :param scale_factor_x: The factor by which to scale the image in the X dimension
+ :type scale_factor_x: float
+ :param scale_factor_y: The factor by which to scale the image in the Y dimension, or None to match the horizontal factor, defaults to None
+ :type scale_factor_y: Union[float, None]
+ :return: The image object, modifications included
+ :rtype: XAImage
- .. versionadded:: 0.0.2
- """
- def__init__(self,file:Union[str,AppKit.NSURL,AppKit.NSImage,None]=None,data:Union[AppKit.NSData,None]=None,name:Union[str,None]=None):
- self.size:Tuple[int,int]#: The dimensions of the image
- self.name:str#: The name of the image
+ .. versionadded:: 0.1.0
+ """
+ ifscale_factor_yisNone:
+ scale_factor_y=scale_factor_x
- ifdataisnotNone:
- self.xa_elem=AppKit.NSImage.alloc().initWithData_(data)
- else:
- iffileisNone:
- self.xa_elem=AppKit.NSImage.alloc().init()
- else:
- ifisinstance(file,AppKit.NSImage):
- self.xa_elem=AppKit.NSImage.alloc().initWithData_(file.TIFFRepresentation())
- else:
- ifisinstance(file,str):
- iffile.startswith("/"):
- file=XAPath(file)
- else:
- file=XAURL(file)
- self.xa_elem=AppKit.NSImage.alloc().initWithContentsOfURL_(file.xa_elem)
- self.name=nameor"image"
+ scaled_image=AppKit.NSImage.alloc().initWithSize_(AppKit.NSMakeSize(self.size[0]*scale_factor_x,self.size[1]*scale_factor_y))
+ imageBounds=AppKit.NSMakeRect(0,0,self.size[0],self.size[1])
- @property
- defsize(self):
- returnself.xa_elem.size()
+ transform=AppKit.NSAffineTransform.alloc().init()
+ transform.scaleXBy_yBy_(scale_factor_x,scale_factor_y)
-
[docs]defpad(self,horizontal_border_width:int=50,vertical_border_width:int=50,pad_color:Union[XAColor,None]=None)->'XAImage':
+ """Pads the image with the specified color; adds a border around the image with the specified vertical and horizontal width.
+
+ :param horizontal_border_width: The border width, in pixels, in the x-dimension, defaults to 50
+ :type horizontal_border_width: int
+ :param vertical_border_width: The border width, in pixels, in the y-dimension, defaults to 50
+ :type vertical_border_width: int
+ :param pad_color: The color of the border, or None for a white border, defaults to None
+ :type pad_color: Union[XAColor, None]
+ :return: The image object, modifications included
+ :rtype: XAImage
+
+ .. versionadded:: 0.1.0
+ """
+ ifpad_colorisNone:
+ # No color provided -- use white by default
+ pad_color=XAColor.white()
+
+ new_width=self.size[0]+horizontal_border_width*2
+ new_height=self.size[1]+vertical_border_width*2
+ color_swatch=pad_color.make_swatch(new_width,new_height)
+
+ color_swatch.xa_elem.lockFocus()
+ bounds=AppKit.NSMakeRect(horizontal_border_width,vertical_border_width,self.size[0],self.size[1])
+ self.xa_elem.drawInRect_(bounds)
+ color_swatch.xa_elem.unlockFocus()
+ self.xa_elem=color_swatch.xa_elem
+ self.modified=True
+ returnself
[docs]defoverlay_image(self,image:'XAImage',location:Union[tuple[int,int],None]=None,size:Union[tuple[int,int],None]=None)->'XAImage':
+ """Overlays an image on top of this image, at the specified location, with the specified size.
-
+ :param image: The image to overlay on top of this image
+ :type image: XAImage
+ :param location: The bottom-left point of the overlaid image in the result, or None to use the bottom-left point of the background image, defaults to None
+ :type location: Union[tuple[int, int], None]
+ :param size: 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 the background image, defaults to None
+ :type size: Union[tuple[int, int], None]
+ :return: The image object, modifications included
+ :rtype: XAImage
+
+ .. versionadded:: 0.1.0
+ """
+ iflocationisNone:
+ # No location provided -- use the bottom-left point of the background image by default
+ location=(0,0)
+
+ ifsizeisNone:
+ # No dimensions provided -- use size of overlay image by default
+ size=image.size
+ elifsize==(-1,-1):
+ # Use remaining width/height of background image
+ size=(self.size[0]-location[0],self.size[1]-location[1])
+ elifsize[0]==-1:
+ # Use remaining width of background image + provided height
+ size=(self.size[0]-location[0],size[1])
+ elifsize[1]==-1:
+ # Use remaining height of background image + provided width
+ size=(size[1],self.size[1]-location[1])
+
+ self.xa_elem.lockFocus()
+ bounds=AppKit.NSMakeRect(location[0],location[1],size[0],size[1])
+ image.xa_elem.drawInRect_(bounds)
+ self.xa_elem.unlockFocus()
+ self.modified=True
+ returnself.xa_elem
+
+
[docs]defoverlay_text(self,text:str,location:Union[tuple[int,int],None]=None,font_size:float=12,font_color:Union[XAColor,None]=None)->'XAImage':
+ """Overlays text of the specified size and color at the provided location within the image.
+
+ :param text: The text to overlay onto the image
+ :type text: str
+ :param location: The bottom-left point of the start of the text, or None to use (5, 5), defaults to None
+ :type location: Union[tuple[int, int], None]
+ :param font_size: The font size, in pixels, of the text, defaults to 12
+ :type font_size: float
+ :param font_color: The color of the text, or None to use black, defaults to None
+ :type font_color: XAColor
+ :return: The image object, modifications included
+ :rtype: XAImage
+
+ .. versionadded:: 0.1.0
+ """
+ iflocationisNone:
+ # No location provided -- use (5, 5) by default
+ location=(5,5)
+
+ iffont_colorisNone:
+ # No color provided -- use black by default
+ font_color=XAColor.black()
+
+ font=AppKit.NSFont.userFontOfSize_(font_size)
+ textRect=Quartz.CGRectMake(location[0],0,self.size[0]-location[0],location[1])
+ attributes={
+ AppKit.NSFontAttributeName:font,
+ AppKit.NSForegroundColorAttributeName:font_color.xa_elem
+ }
+ self.xa_elem.lockFocus()
+ AppKit.NSString.alloc().initWithString_(text).drawInRect_withAttributes_(textRect,attributes)
+ self.xa_elem.unlockFocus()
+ self.modified=True
+ returnself
+
[docs]defextract_text(self)->list[str]:
+ """Extracts and returns all visible text in the image.
+ :return: The array of extracted text strings
+ :rtype: list[str]
-# TODO: Init NSLocation object
-
[docs]classXALocation(XAObject):
- """A location with a latitude and longitude, along with other data.
+ :Example:
- .. versionadded:: 0.0.2
- """
- def__init__(self,raw_value:CoreLocation.CLLocation=None,title:str=None,latitude:float=0,longitude:float=0,altitude:float=None,radius:int=0,address:str=None):
- self.raw_value=raw_value#: The raw CLLocation object
- self.title=title#: The name of the location
- self.latitude=latitude#: The latitude of the location
- self.longitude=longitude#: The longitude of the location
- self.altitude=altitude#: The altitude of the location
- self.radius=radius#: The horizontal accuracy of the location measurement
- self.address=address#: The addres of the location
- self.current_location#: The current location of the device
+ >>> 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', ...]
+
+ .. versionadded:: 0.1.0
+ """
+ # Prepare CGImage
+ ci_image=Quartz.CIImage.imageWithData_(self.data)
+ context=Quartz.CIContext.alloc().initWithOptions_(None)
+ img=context.createCGImage_fromRect_(ci_image,ci_image.extent())
+
+ # Handle request completion
+ extracted_strings=[]
+ defrecognize_text_handler(request,error):
+ observations=request.results()
+ forobservationinobservations:
+ recognized_strings=observation.topCandidates_(1)[0].string()
+ extracted_strings.append(recognized_strings)
+
+ # Perform request and return extracted text
+ request=Vision.VNRecognizeTextRequest.alloc().initWithCompletionHandler_(recognize_text_handler)
+ request_handler=Vision.VNImageRequestHandler.alloc().initWithCGImage_options_(img,None)
+ request_handler.performRequests_error_([request],None)
+ returnextracted_strings
[docs]defshow_in_maps(self):
- """Shows the location in Maps.app.
+
[docs]defsave(self,file_path:Union[XAPath,str,None]=None):
+ """Saves the image to a file on the disk. Saves to the original file (if there was one) by default.
- .. versionadded:: 0.0.6
+ :param file_path: The path at which to save the image file. Any existing file at that location will be overwritten, defaults to None
+ :type file_path: Union[XAPath, str, None]
+
+ .. versionadded:: 0.1.0 """
- XAURL(f"maps://?q={self.title},ll={self.latitude},{self.longitude}").open()
[docs]defget_clipboard_representation(self)->AppKit.NSImage:
+ """Gets a clipboard-codable representation of the iimage.
- deflocationManager_didFailWithError_(self,manager,error):
- print(manager,error)
+ 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.
- location_manager.requestWhenInUseAuthorization()
- location_manager.setDelegate_(CLLocationManagerDelegate.alloc().init().retain())
- location_manager.requestLocation()
+ :return: The raw NSImage object for this XAIMage
+ :rtype: AppKit.NSImage
- AppHelper.runConsoleEventLoop()
+ .. versionadded:: 0.1.0
+ """
+ returnself.xa_elem
[docs]classXAAlertStyle(Enum):
- """Options for which alert style an alert should display with.
- """
- INFORMATIONAL=AppKit.NSAlertStyleInformational
- WARNING=AppKit.NSAlertStyleWarning
- CRITICAL=AppKit.NSAlertStyleCritical
-
[docs]classXAAlert(XAObject):
- """A class for creating and interacting with an alert dialog window.
- .. versionadded:: 0.0.5
+
[docs]classXASoundList(XAList,XAClipboardCodable):
+ """A wrapper around lists of sounds that employs fast enumeration techniques.
+
+ .. versionadded:: 0.1.0 """
- def__init__(self,title:str="Alert!",message:str="",style:XAAlertStyle=XAAlertStyle.INFORMATIONAL,buttons=["Ok","Cancel"]):
- super().__init__()
- self.title:str=title
- self.message:str=message
- self.style:XAAlertStyle=style
- self.buttons:List[str]=buttons
+ def__init__(self,properties:dict,filter:Union[dict,None]=None):
+ super().__init__(properties,XASound,filter)
-
[docs]defdisplay(self)->int:
- """Displays the alert.
+
[docs]defget_clipboard_representation(self)->list[Union[AppKit.NSSound,AppKit.NSURL,str]]:
+ """Gets a clipboard-codable representation of each sound in the list.
- :return: A number representing the button that the user selected, if any
- :rtype: int
+ When the clipboard content is set to a list of sounds, each sound's raw sound data, its associated file URL, and its file path string are added to the clipboard.
- .. versionadded:: 0.0.5
- """
- alert=AppKit.NSAlert.alloc().init()
- alert.setMessageText_(self.title)
- alert.setInformativeText_(self.message)
- alert.setAlertStyle_(self.style.value)
+ :return: The clipboard-codable form of the sound
+ :rtype: Any
- forbuttoninself.buttons:
- alert.addButtonWithTitle_(button)
- returnalert.runModal()
[docs]classXASound(XAObject,XAClipboardCodable):
+ """A class for playing and interacting with audio files and data.
+ .. versionadded:: 0.0.1
+ """
+ def__init__(self,sound_reference:Union[str,XAURL,XAPath]):
+ self.file=None
+ matchsound_reference:
+ casestr()asrefif"://"inref:
+ logging.debug(f"Sound ref is web/file URL --> Set file to URL")
+ self.file=XAURL(ref)
-
[docs]classXAColorPickerStyle(Enum):
- """Options for which tab a color picker should display when first opened.
- """
- GRAYSCALE=AppKit.NSColorPanelModeGray
- RGB_SLIDERS=AppKit.NSColorPanelModeRGB
- CMYK_SLIDERS=AppKit.NSColorPanelModeCMYK
- HSB_SLIDERS=AppKit.NSColorPanelModeHSB
- COLOR_LIST=AppKit.NSColorPanelModeColorList
- COLOR_WHEEL=AppKit.NSColorPanelModeWheel
- CRAYONS=AppKit.NSColorPanelModeCrayon
- IMAGE_PALETTE=AppKit.NSColorPanelModeCustomPalette
+ casestr()asrefifos.path.exists(ref):
+ logging.debug(f"Sound ref is file path --> Set file to path")
+ self.file=XAPath(sound_reference)
-
[docs]classXAColorPicker(XAObject):
- """A class for creating and interacting with a color picker window.
+ casestr()asref:
+ logging.debug(f"Sound ref is raw string --> Set file to path of sound with ref name")
+ self.file=XAPath("/System/Library/Sounds/"+ref+".aiff")
- .. versionadded:: 0.0.5
- """
- def__init__(self,style:XAColorPickerStyle=XAColorPickerStyle.GRAYSCALE):
- super().__init__()
- self.style=style
+ case{"element":str()asref}:
+ logging.debug(f"Sound ref is string from XASoundList --> Reinit with string")
+ self.file=XASound(ref).file
-
[docs]defdisplay(self)->XAColor:
- """Displays the color picker.
+ caseXAPath()asref:
+ logging.debug(f"Sound ref is path object --> Set file to path")
+ self.file=ref
- :return: The color that the user selected
- :rtype: XAColor
+ caseXAURL()asref:
+ logging.debug(f"Sound ref is web/file URL object --> Set file to URL")
+ self.file=ref
- .. versionadded:: 0.0.5
- """
- panel=AppKit.NSColorPanel.sharedColorPanel()
- panel.setMode_(self.style.value)
- panel.setShowsAlpha_(True)
+ caseXASound()assound:
+ logging.debug(f"Sound ref is another XASound object --> Set file to that sound's file")
+ self.file=sound.file
- defrun_modal(panel):
- initial_color=panel.color()
- time.sleep(0.5)
- whilepanel.isVisible()andpanel.color()==initial_color:
- time.sleep(0.01)
- AppKit.NSApp.stopModal()
+ self.duration:float#: The duration of the sound in seconds
- modal_thread=threading.Thread(target=run_modal,args=(panel,),name="Run Modal",daemon=True)
- modal_thread.start()
+ self.__audio_file=AVFoundation.AVAudioFile.alloc().initForReading_error_(self.file.xa_elemifself.fileisnotNoneelseNone,None)[0]
- AppKit.NSApp.runModalForWindow_(panel)
- returnXAColor(panel.color())
[docs]defdisplay(self)->Union[str,int,None,List[str]]:
- """Displays the dialog, waits for the user to select an option or cancel, then returns the selected button or None if cancelled.
+ @property
+ defsample_rate(self)->float:
+ """The sample rate for the sound format, in hertz.
- :return: The selected button or None if no value was selected
- :rtype: Union[str, int, None, List[str]]
+ .. versionadded:: 0.1.0
+ """
+ returnself.xa_elem.processingFormat().sampleRate()
- .. versionadded:: 0.0.8
+ @property
+ defduration(self)->float:
+ """The duration of the sound in seconds.
+
+ .. versionadded:: 0.1.0 """
- buttons=[x.replace("'","")forxinself.buttons]
- buttons=str(buttons).replace("'",'"')
+ returnself.num_sample_frames/self.sample_rate
- default_button=str(self.default_button).replace("'","")
- default_button_str="default button \""+default_button+"\""ifself.default_buttonisnotNoneelse""
+
[docs]defopen(*sound_references:Union[str,XAPath,list[Union[str,XAPath]]])->Union['XASound',XASoundList]:
+ """Initializes one or more sounds from files.
- cancel_button=str(self.cancel_button).replace("'","")
- cancel_button_str="cancel button \""+cancel_button+"\""ifself.cancel_buttonisnotNoneelse""
+ :param sound_references: The sound(s) to open
+ :type sound_references: Union[str, XAPath, list[Union[str, XAPath]]]
+ :return: The newly created sound object, or a list of sound objects
+ :rtype: Union[XASound, XASoundList]
- icon_str="with icon "+self.icon+""ifself.iconisnotNoneelse""
+ .. versionadded:: 0.1.0
+ """
+ iflen(sound_references)==1:
+ sound_references=sound_references[0]
- default_answer=str(self.default_answer).replace("'",'"')
- default_answer_str="default answer \""+default_answer+"\""ifself.default_answerisnotNoneelse""
+ ifisinstance(sound_references,list)orisinstance(sound_references,tuple):
+ returnXASoundList({"element":sound_references})
+ else:
+ returnXASound(sound_references)
- script=AppleScript(f"""
- tell application "Terminal"
- display dialog \"{self.text}\" with title \"{self.title}\" buttons {buttons}{default_button_str}{cancel_button_str}{icon_str}{default_answer_str} hidden answer {self.hidden_answer}
- end tell
- """)
+
[docs]defbeep():
+ """Plays the system Beep sound.
- result=script.run()["event"]
- ifresultisnotNone:
- ifresult.numberOfItems()>1:
- return[result.descriptorAtIndex_(1).stringValue(),result.descriptorAtIndex_(2).stringValue()]
- else:
- returnresult.descriptorAtIndex_(1).stringValue()
[docs]defplay(self)->Self:
+ """Plays the sound from the beginning.
+ Audio playback runs in a separate thread. For the sound the play properly, you must keep the main thread alive over the duration of the desired playback.
-
[docs]classXAMenu(XAObject):
- """A custom list item selection menu.
+ :return: A reference to this sound object.
+ :rtype: Self
- .. versionadded:: 0.0.8
- """
- def__init__(self,menu_items:List[Any],title:str="Select Item",prompt:str="Select an item",default_items:Union[List[str],None]=None,ok_button_name:str="Okay",cancel_button_name:str="Cancel",multiple_selections_allowed:bool=False,empty_selection_allowed:bool=False):
- super().__init__()
- self.menu_items:List[Union[str,int]]=menu_items#: The items the user can choose from
- self.title:str=title#: The title of the dialog window
- self.prompt:str=prompt#: The prompt to display in the dialog box
- self.default_items:List[str]=default_itemsor[]#: The items to initially select
- self.ok_button_name:str=ok_button_name#: The name of the OK button
- self.cancel_button_name:str=cancel_button_name#: The name of the Cancel button
- self.multiple_selections_allowed:bool=multiple_selections_allowed#: Whether multiple items can be selected
- self.empty_selection_allowed:bool=empty_selection_allowed#: Whether the user can click OK without selecting anything
+ :Example:
-
[docs]defdisplay(self)->Union[str,int,bool,List[str],List[int]]:
- """Displays the menu, waits for the user to select an option or cancel, then returns the selected value or False if cancelled.
+ >>> import PyXA
+ >>> import time
+ >>> glass_sound = PyXA.sound("Glass")
+ >>> glass_sound.play()
+ >>> time.sleep(glass_sound.duration)
- :return: The selected value or False if no value was selected
- :rtype: Union[str, int, bool, List[str], List[int]]
+ .. seealso:: :func:`pause`, :func:`stop`
- .. versionadded:: 0.0.8
+ .. versionadded:: 0.0.1 """
- menu_items=[x.replace("'","")forxinself.menu_items]
- menu_items=str(menu_items).replace("'",'"')
- default_items=str(self.default_items).replace("'",'"')
- script=AppleScript(f"""
- tell application "Terminal"
- choose from list {menu_items} with title \"{self.title}\" with prompt \"{self.prompt}\" default items {default_items} OK button name \"{self.ok_button_name}\" cancel button name \"{self.cancel_button_name}\" multiple selections allowed {self.multiple_selections_allowed} empty selection allowed {self.empty_selection_allowed}
- end tell
- """)
- result=script.run()["event"]
- ifresultisnotNone:
- ifself.multiple_selections_allowed:
- values=[]
- forxinrange(1,result.numberOfItems()+1):
- desc=result.descriptorAtIndex_(x)
- values.append(desc.stringValue())
- returnvalues
- else:
- ifresult.stringValue()=="false":
- returnFalse
- returnresult.stringValue()
[docs]defpause(self)->Self:
+ """Pauses the sound.
-
[docs]classXAFilePicker(XAObject):
- """A file selection window.
+ :return: A reference to this sound object.
+ :rtype: Self
- .. versionadded:: 0.0.8
- """
- def__init__(self,prompt:str="Choose File",types:List[str]=None,default_location:Union[str,None]=None,show_invisibles:bool=False,multiple_selections_allowed:bool=False,show_package_contents:bool=False):
- super().__init__()
- self.prompt:str=prompt#: The prompt to display in the dialog box
- self.types:List[str]=types#: The file types/type identifiers to allow for selection
- self.default_location:Union[str,None]=default_location#: The default file location
- self.show_invisibles:bool=show_invisibles#: Whether invisible files and folders are shown
- self.multiple_selections_allowed:bool=multiple_selections_allowed#: Whether the user can select multiple files
- self.show_package_contents:bool=show_package_contents#: Whether to show the contents of packages
+ :Example:
-
[docs]defdisplay(self)->Union[XAPath,None]:
- """Displays the file chooser, waits for the user to select a file or cancel, then returns the selected file URL or None if cancelled.
+ >>> import PyXA
+ >>> glass_sound = PyXA.sound("Glass")
+ >>> glass_sound.pause()
- :return: The selected file URL or None if no file was selected
- :rtype: Union[XAPath, None]
+ .. seealso:: :func:`resume`, :func:`stop`
- .. versionadded:: 0.0.8
+ .. versionadded:: 0.0.1 """
- types=[x.replace("'","")forxinself.types]
- types=str(types).replace("'",'"')
- types_str="of type "+typesifself.typesisnotNoneelse""
+ self.__player_node.pause()
+ returnself
[docs]defresume(self)->Self:
+ """Plays the sound starting from the time it was last paused at.
- script=AppleScript(f"""
- tell application "Terminal"
- choose file with prompt \"{self.prompt}\"{types_str}{default_location_str} invisibles {self.show_invisibles} multiple selections allowed {self.multiple_selections_allowed} showing package contents {self.show_package_contents}
- end tell
- """)
- result=script.run()["event"]
+ Audio playback runs in a separate thread. For the sound the play properly, you must keep the main thread alive over the duration of the desired playback.
- ifresultisnotNone:
- ifself.multiple_selections_allowed:
- values=[]
- forxinrange(1,result.numberOfItems()+1):
- desc=result.descriptorAtIndex_(x)
- values.append(XAPath(desc.fileURLValue()))
- returnvalues
- else:
- returnXAPath(result.fileURLValue())
[docs]classXAFolderPicker(XAObject):
- """A folder selection window.
+ .. versionadded:: 0.0.1
+ """
+ defplay_sound(self):
+ self.__player_node.scheduleFile_atTime_completionHandler_(self.xa_elem,None,None)
+ self.__audio_engine.startAndReturnError_(None)
+ self.__player_node.play()
+ whileself.__player_node.isPlaying():
+ AppKit.NSRunLoop.currentRunLoop().runUntilDate_(datetime.now()+timedelta(seconds=0.1))
- .. versionadded:: 0.0.8
- """
- def__init__(self,prompt:str="Choose Folder",default_location:Union[str,None]=None,show_invisibles:bool=False,multiple_selections_allowed:bool=False,show_package_contents:bool=False):
- super().__init__()
- self.prompt:str=prompt#: The prompt to display in the dialog box
- self.default_location:Union[str,None]=default_location#: The default folder location
- self.show_invisibles:bool=show_invisibles#: Whether invisible files and folders are shown
- self.multiple_selections_allowed:bool=multiple_selections_allowed#: Whether the user can select multiple folders
- self.show_package_contents:bool=show_package_contents#: Whether to show the contents of packages
+ self._spawn_thread(play_sound,[self])
+ returnself
-
[docs]defdisplay(self)->Union[XAPath,None]:
- """Displays the folder chooser, waits for the user to select a folder or cancel, then returns the selected folder URL or None if cancelled.
+
[docs]defstop(self)->'XASound':
+ """Stops playback of the sound and rewinds it to the beginning.
- :return: The selected folder URL or None if no folder was selected
- :rtype: Union[XAPath, None]
+ :return: A reference to this sound object.
+ :rtype: XASound
- .. versionadded:: 0.0.8
+ :Example:
+
+ >>> import PyXA
+ >>> glass_sound = PyXA.sound("Glass")
+ >>> glass_sound.stop()
+
+ .. seealso:: :func:`pause`, :func:`play`
+
+ .. versionadded:: 0.0.1 """
+ self.__audio_engine.stop()
+ returnself
+ :param volume: The desired volume of the sound in the range [0.0, 1.0].
+ :type volume: int
+ :return: A reference to this sound object.
+ :rtype: Self
+ :Example:
+ >>> import PyXA
+ >>> glass_sound = PyXA.sound("Glass")
+ >>> glass_sound.set_volume(1.0)
+ .. seealso:: :func:`volume`
-
- .. versionadded:: 0.0.8
- """
- def__init__(self,prompt:str="Specify file name and location",default_name:str="New File",default_location:Union[str,None]=None):
- super().__init__()
- self.prompt:str=prompt#: The prompt to display in the dialog box
- self.default_name:str=default_name#: The default name for the new file
- self.default_location:Union[str,None]=default_location#: The default file location
+
[docs]defvolume(self)->float:
+ """Returns the current volume of the sound.
-
[docs]defdisplay(self)->Union[XAPath,None]:
- """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.
+ :return: The volume level of the sound.
+ :rtype: int
- :return: The specified file URL or None if no file name was inputted
- :rtype: Union[XAPath, None]
+ :Example:
- .. versionadded:: 0.0.8
+ >>> import PyXA
+ >>> glass_sound = PyXA.sound("Glass")
+ >>> print(glass_sound.volume())
+ 1.0
+
+ .. seealso:: :func:`set_volume`
+
+ .. versionadded:: 0.0.1 """
+ returnself.__audio_engine.mainMixerNode().volume()
[docs]defloop(self,times:int)->Self:
+ """Plays the sound the specified number of times.
- script=AppleScript(f"""
- tell application "Terminal"
- choose file name with prompt \"{self.prompt}\" default name \"{self.default_name}\"{default_location_str}
- end tell
- """)
- result=script.run()["event"]
- ifresultisnotNone:
- returnXAPath(result.fileURLValue())
+ Audio playback runs in a separate thread. For the sound the play properly, you must keep the main thread alive over the duration of the desired playback.
+ :param times: The number of times to loop the sound.
+ :type times: int
+ :return: A reference to this sound object.
+ :rtype: Self
+ :Example:
+ >>> import PyXA
+ >>> import time
+ >>> glass_sound = PyXA.sound("Glass")
+ >>> glass_sound.loop(10)
+ >>> time.sleep(glass_sound.duration * 10)
-
[docs]classXASpeech(XAObject):
- def__init__(self,message:str="",voice:Union[str,None]=None,volume:float=0.5,rate:int=200):
- self.message:str=message#: The message to speak
- self.voice:Union[str,None]=voice#: The voice that the message is spoken in
- self.volume:float=volume#: The speaking volume
- self.rate:int=rate#: The speaking rate
+ .. versionadded:: 0.0.1
+ """
+ defplay_sound():
+ num_plays=0
+ whilenum_plays<times:
+ sound=XASound(self.file)
+ sound.play()
+ num_plays+=1
+ time.sleep(self.duration)
-
[docs]defvoices(self)->List[str]:
- """Gets the list of voice names available on the system.
+ self._spawn_thread(play_sound)
+ returnself
- :return: The list of voice names
- :rtype: List[str]
+
[docs]deftrim(self,start_time:float,end_time:float)->Self:
+ """Trims the sound to the specified start and end time, in seconds.
- :Example:
+ This will create a momentary sound data file in the current working directory for storing the intermediary trimmed sound data.
- >>> import PyXA
- >>> speaker = PyXA.XASpeech()
- >>> print(speaker.voices())
- ['Agnes', 'Alex', 'Alice', 'Allison',
+ :param start_time: The start time in seconds
+ :type start_time: float
+ :param end_time: The end time in seconds
+ :type end_time: float
+ :return: The updated sound object
+ :rtype: Self
- .. versionadded:: 0.0.9
+ .. versionadded:: 0.1.0 """
- ls=AppKit.NSSpeechSynthesizer.availableVoices()
- return[x.replace("com.apple.speech.synthesis.voice.","").replace(".premium","").title()forxinls]
-
-
[docs]defspeak(self,path:Union[str,XAPath,None]=None):
- """Speaks the provided message using the desired voice, volume, and speaking rate.
+ # Clear the temp data path
+ file_path="sound_data_tmp.m4a"
+ ifos.path.exists(file_path):
+ AppKit.NSFileManager.defaultManager().removeItemAtPath_error_(file_path,None)
- :param path: The path to a .AIFF file to output sound to, defaults to None
- :type path: Union[str, XAPath, None], optional
+ # Configure the export session
+ asset=AVFoundation.AVAsset.assetWithURL_(self.file.xa_elem)
+ export_session=AVFoundation.AVAssetExportSession.exportSessionWithAsset_presetName_(asset,AVFoundation.AVAssetExportPresetAppleM4A)
- :Example 1: Speak a message aloud
+ start_time=CoreMedia.CMTimeMake(start_time*100,100)
+ end_time=CoreMedia.CMTimeMake(end_time*100,100)
+ time_range=CoreMedia.CMTimeRangeFromTimeToTime(start_time,end_time);
- >>> import PyXA
- >>> PyXA.XASpeech("This is a test").speak()
+ export_session.setTimeRange_(time_range)
+ export_session.setOutputURL_(XAPath(file_path).xa_elem)
+ export_session.setOutputFileType_(AVFoundation.AVFileTypeAppleM4A)
- :Example 2: Output spoken message to an AIFF file
+ # Export to file path
+ waiting=False
+ defhandler():
+ nonlocalwaiting
+ waiting=True
- >>> import PyXA
- >>> speaker = PyXA.XASpeech("Hello, world!")
- >>> speaker.speak("/Users/steven/Downloads/Hello.AIFF")
+ export_session.exportAsynchronouslyWithCompletionHandler_(handler)
- :Example 3: Control the voice, volume, and speaking rate
+ whilenotwaiting:
+ time.sleep(0.01)
- >>> import PyXA
- >>> speaker = PyXA.XASpeech(
- >>> message = "Hello, world!",
- >>> voice = "Alex",
- >>> volume = 1,
- >>> rate = 500
- >>> )
- >>> speaker.speak()
+ # Load the sound file back into active memory
+ self.__audio_file=AVFoundation.AVAudioFile.alloc().initForReading_error_(XAPath(file_path).xa_elem,None)[0]
+ self.xa_elem=self.__audio_file
+ AppKit.NSFileManager.defaultManager().removeItemAtPath_error_(file_path,None)
+ returnself
- .. versionadded:: 0.0.9
- """
- # Get the selected voice by name
- voice=None
- forvinAppKit.NSSpeechSynthesizer.availableVoices():
- ifself.voice.lower()inv.lower():
- voice=v
+
[docs]defsave(self,file_path:Union[XAPath,str]):
+ """Saves the sound to the specified file path.
- # Set up speech synthesis object
- synthesizer=AppKit.NSSpeechSynthesizer.alloc().initWithVoice_(voice)
- synthesizer.setVolume_(self.volume)
- synthesizer.setRate_(self.rate)
+ :param file_path: The path to save the sound to
+ :type file_path: Union[XAPath, str]
- # Start speaking
- ifpathisNone:
- synthesizer.startSpeakingString_(self.message)
- else:
- ifisinstance(path,str):
- path=XAPath(path)
- synthesizer.startSpeakingString_toURL_(self.message,path.xa_elem)
+ .. versionadded:: 0.1.0
+ """
+ ifisinstance(file_path,str):
+ file_path=XAPath(file_path)
- # Wait for speech to complete
- whilesynthesizer.isSpeaking():
- time.sleep(0.01)
[docs]classXAMenuBar(XAObject):
- def__init__(self):
- """Creates a new menu bar object for interacting with the system menu bar.
+ export_session.exportAsynchronouslyWithCompletionHandler_(handler)
+
+ whilenotwaiting:
+ time.sleep(0.01)
[docs]defget_clipboard_representation(self)->list[Union[AppKit.NSSound,AppKit.NSURL,str]]:
+ """Gets a clipboard-codable representation of the sound.
- detector=self
- classMyApplicationAppDelegate(AppKit.NSObject):
- start_time=datetime.now()
+ When the clipboard content is set to a sound, the raw sound data, the associated file URL, and the path string of the file are added to the clipboard.
- defapplicationDidFinishLaunching_(self,sender):
- foritem_name,status_itemindetector._menus.items():
- menu=status_item.menu()
+ :return: The clipboard-codable form of the sound
+ :rtype: Any
- menuitem=AppKit.NSMenuItem.alloc().initWithTitle_action_keyEquivalent_('Quit','terminate:','')
- menu.addItem_(menuitem)
+ .. versionadded:: 0.0.8
+ """
+ return[self.xa_elem,self.file.xa_elem,self.file.xa_elem.path()]
[docs]defadd_menu(self,title:str,image:Union[XAImage,None]=None,tool_tip:Union[str,None]=None,img_width:int=30,img_height:int=30):
- """Adds a new menu to be displayed in the system menu bar.
+
[docs]classXAVideo(XAObject):
+ """A class for interacting with video files and data.
- :param title: The name of the menu
- :type title: str
- :param image: The image to display for the menu, defaults to None
- :type image: Union[XAImage, None], optional
- :param tool_tip: The tooltip to display on hovering over the menu, defaults to None
- :type tool_tip: Union[str, None], optional
- :param img_width: The width of the image, in pixels, defaults to 30
- :type img_width: int, optional
- :param img_height: The height of the image, in pixels, defaults to 30
- :type img_height: int, optional
+ .. versionadded:: 0.1.0
+ """
+ def__init__(self,video_reference:Union[str,XAURL,XAPath]):
+ ifisinstance(video_reference,str):
+ # References is to some kind of path or URL
+ if"://"invideo_reference:
+ video_reference=XAURL(video_reference)
+ else:
+ video_reference=XAPath(video_reference)
- :Example:
+ self.xa_elem=AVFoundation.AVURLAsset.alloc().initWithURL_options_(video_reference.xa_elem,{AVFoundation.AVURLAssetPreferPreciseDurationAndTimingKey:objc.YES})
- >>> import PyXA
- >>> menu_bar = PyXA.XAMenuBar()
- >>> img = PyXA.XAImage("/Users/steven/Downloads/Blackness.jpg")
- >>> menu_bar.add_menu("Menu 1", image=img, img_width=100, img_height=100)
- >>> menu_bar.display()
+
[docs]defreverse(self,output_file:Union[XAPath,str]):
+ """Reverses the video and exports the result to the specified output file path.
- .. versionadded:: 0.0.9
+ :param output_file: The file to export the reversed video to
+ :type output_file: Union[XAPath, str]
+
+ .. versionadded:: 0.1.0 """
- status_bar=AppKit.NSStatusBar.systemStatusBar()
- status_item=status_bar.statusItemWithLength_(AppKit.NSVariableStatusItemLength).retain()
- status_item.setTitle_(title)
-
- ifisinstance(image,XAImage):
- img=image.xa_elem.copy()
- img.setScalesWhenResized_(True)
- img.setSize_((img_width,img_height))
- status_item.button().setImage_(img)
+ ifisinstance(output_file,str):
+ output_file=XAPath(output_file)
+ output_url=output_file.xa_elem
- status_item.setHighlightMode_(objc.YES)
+ reader=AVFoundation.AVAssetReader.alloc().initWithAsset_error_(self.xa_elem,None)[0]
- ifisinstance(tool_tip,str):
- status_item.setToolTip_(tool_tip)
+ video_track=self.xa_elem.tracksWithMediaType_(AVFoundation.AVMediaTypeVideo)[-1]
+
+ reader_output=AVFoundation.AVAssetReaderTrackOutput.alloc().initWithTrack_outputSettings_(video_track,{Quartz.CoreVideo.kCVPixelBufferPixelFormatTypeKey:Quartz.CoreVideo.kCVPixelFormatType_420YpCbCr8BiPlanarVideoRange})
- menu=AppKit.NSMenu.alloc().init()
- status_item.setMenu_(menu)
+ reader.addOutput_(reader_output)
+ reader.startReading()
- status_item.setEnabled_(objc.YES)
- self._menus[title]=status_item
[docs]defshow_in_quicktime(self):
+ """Shows the video in QuickTime Player.
- .. versionadded:: 0.0.9
- """
- img=image.xa_elem.copy()
- img.setScalesWhenResized_(True)
- img.setSize_((img_width,img_height))
- ifitem_nameinself._menus:
- self._menus[item_name].button().setImage_(img)
- elifitem_nameinself._methods:
- self._menu_items[item_name].setImage_(img)
+ This will create a momentary video data file in the current working directory to store intermediary video data.
-
[docs]defset_text(self,item_name:str,text:str):
- """Sets the text displayed for a menu or menu item.
+ .. versionadded:: 0.1.0
+ """
+ self.save("video-data-tmp.mp4")
- :param item_name: The name of the item to update
- :type item_name: str
- :param text: The new text to display
- :type text: str
+ video_url=XAPath(os.getcwd()+"/video-data-tmp.mp4").xa_elem
+ quicktime_url=XAPath("/System/Applications/QuickTime Player.app").xa_elem
+ AppKit.NSWorkspace.sharedWorkspace().openURLs_withApplicationAtURL_configuration_completionHandler_([video_url],quicktime_url,None,None)
+ time.sleep(1)
- :Example: Random Emoji Ticker
+ AppKit.NSFileManager.defaultManager().removeItemAtPath_error_(video_url.path(),None)
[docs]defsave(self,file_path:Union[XAPath,str]):
+ """Saves the video at the specified file path.
- .. versionadded:: 0.0.9
+ :param file_path: The path to save the video at
+ :type file_path: Union[XAPath, str]
+
+ .. versionadded:: 0.1.0 """
- ifitem_nameinself._menus:
- self._menus[item_name].setTitle_(text)
- elifitem_nameinself._methods:
- self._menu_items[item_name].setTitle_(text)
- self._methods[text]=self._methods[item_name]
[docs]defprint(self,properties:dict=None,print_dialog=None)->XABase.XAObject:
+ """Prints a document, window, or item.
+
+ :return: A reference to the PyXA objects that called this method.
+ :rtype: XABase.XAObject
+
+ .. versionchanged:: 0.0.2
+ Printing now initialized from a separate thread to avoid delaying main thread
+
+ .. versionadded:: 0.0.1
+ """
+ print_thread=threading.Thread(target=self.__print_dialog,name="Print",daemon=True)
+ print_thread.start()
+ returnself
+
+
+
+
+
[docs]classXASBApplication(XASBObject,XABase.XAApplication):
+ """An application class for scriptable applications.
+
+ .. seealso:: :class:`XABase.XAApplication`, :class:`XABase.XAWindow`
+ """
+
[docs]classSaveOption(Enum):
+ """Options for whether to save documents when closing them.
+ """
+ YES=XABase.OSType('yes ')#: Save the file
+ NO=XABase.OSType('no ')#: Do not save the file
+ ASK=XABase.OSType('ask ')#: Ask user whether to save the file (bring up dialog)
+
+
[docs]classPrintErrorHandling(Enum):
+ """Options for how to handle errors while printing.
+ """
+ STANDARD='lwst'#: Standard PostScript error handling
+ DETAILED='lwdt'#: Print a detailed report of PostScript errors
+
+ def__init__(self,properties):
+ super().__init__(properties)
+ self.xa_scel=ScriptingBridge.SBApplication.alloc().initWithBundleIdentifier_(self.xa_elem.bundleIdentifier())
+ self.xa_wcls=XASBWindow
+
+ self.front_window:XASBWindow#: The front window of the application
+
+ @property
+ deffront_window(self)->'XASBWindow':
+ returnself._new_element(self.xa_scel.windows()[0],self.xa_wcls)
+
+
[docs]defcollapse(self):
+ """Collapses all windows in the list.
+
+ .. versionadded:: 0.0.5
+ """
+ forwindowinself:
+ window.collapse()
+
+
[docs]defget_clipboard_representation(self)->str:
+ """Gets a clipboard-codable representation of each window in the list.
+
+ When the clipboard content is set to a list of windows, the name of each window is added to the clipboard.
+
+ :return: A list of window names
+ :rtype: str
+
+ .. versionadded:: 0.0.8
+ """
+ returnself.name()
[docs]classXASBWindow(XASBObject,XACloseable):
+ def__init__(self,properties):
+ super().__init__(properties)
+ self.name:str#: The title of the window
+ self.id:str#: The unique identifier for the window
+ self.index:int#: The index of the window, ordered front to back
+ self.bounds:Tuple[Tuple[int,int]]#: The bounding rectangle of the window
+ self.closeable:bool#: Whether the window has a close button
+ self.resizable:bool#: Whether the window can be resized
+ self.visible:bool#: Whether the window is currently visible
+ self.zoomable:bool#: Whether the window has a zoom button
+ self.zoomed:bool#: Whether the window is currently zoomed
+
+ @property
+ defname(self)->str:
+ returnself.xa_elem.name()
+
+ @property
+ defid(self)->str:
+ returnself.xa_elem.id()
+
+ @property
+ defindex(self)->int:
+ returnself.xa_elem.index()
+
+ @property
+ defbounds(self)->Tuple[Tuple[int,int]]:
+ returnself.xa_elem.bounds()
+
+ @property
+ defcloseable(self)->bool:
+ returnself.xa_elem.closeable()
+
+ @property
+ defresizable(self)->bool:
+ returnself.xa_elem.resizable()
+
+ @property
+ defvisible(self)->bool:
+ returnself.xa_elem.visible()
+
+ @property
+ defzoomable(self)->bool:
+ returnself.xa_elem.zoomable()
+
+ @property
+ defzoomed(self)->bool:
+ returnself.xa_elem.zoomed()
+
+
[docs]defcollapse(self)->'XABase.XAWindow':
+ """Collapses (minimizes) the window.
+
+ :return: A reference to the now-collapsed window object.
+ :rtype: XABase.XAWindow
+ """
+ try:
+ self.set_property("miniaturized",True)
+ except:
+ try:
+ self.set_property("minimized",True)
+ except:
+ self.set_property("collapsed",True)
+ returnself
+
+
[docs]defuncollapse(self)->'XABase.XAWindow':
+ """Uncollapses (unminimizes/expands) the window.
+
+ :return: A reference to the uncollapsed window object.
+ :rtype: XABase.XAWindow
+ """
+ try:
+ self.set_property("miniaturized",False)
+ except:
+ try:
+ self.set_property("minimized",False)
+ except:
+ self.set_property("collapsed",False)
+ returnself
+
+
[docs]deftoggle_zoom(self)->'XABase.XAWindow':
+ """Uncollapses (unminimizes/expands) the window.
+
+ :return: A reference to the uncollapsed window object.
+ :rtype: XABase.XAWindow
+ """
+ self.zoomed=notself.zoomed
+ self.set_property("zoomed",self.zoomed)
+ returnself
[docs]defget_clipboard_representation(self)->str:
+ """Gets a clipboard-codable representation of the window.
+
+ When the clipboard content is set to a window, the name of the window is added to the clipboard.
+
+ :return: The name of the window
+ :rtype: str
+
+ .. versionadded:: 0.0.8
+ """
+ returnself.name
+
+
+
+
+
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/docs/_modules/PyXA/XABaseScriptable.html b/docs/_modules/PyXA/XABaseScriptable.html
index ce4a387..ff21496 100644
--- a/docs/_modules/PyXA/XABaseScriptable.html
+++ b/docs/_modules/PyXA/XABaseScriptable.html
@@ -3,7 +3,7 @@
- PyXA.XABaseScriptable — PyXA 0.0.9 documentation
+ PyXA.XABaseScriptable — PyXA 0.1.0 documentation
@@ -14,7 +14,9 @@
+
+
@@ -69,6 +71,7 @@
def__init__(self,properties):super().__init__(properties)
- self.xa_scel=ScriptingBridge.SBApplication.alloc().initWithBundleIdentifier_(self.xa_elem.bundleIdentifier())
+ self.xa_scel=ScriptingBridge.SBApplication.alloc().initWithURL_(self.xa_elem.bundleURL())self.xa_wcls=XASBWindow
- self.front_window:XASBWindow#: The front window of the application
-
@propertydeffront_window(self)->'XASBWindow':
+ """The front window of the application.
+
+ .. versionadded:: 0.0.1
+ """returnself._new_element(self.xa_scel.windows()[0],self.xa_wcls)
[docs]classXAAutomatorApplication(XABaseScriptable.XASBApplication,XACanOpenPath):
+ """A class for managing and interacting with Automator.app.
+
+ .. seealso:: :class:`XAAutomatorWindow`, :class:`XAAutomatorDocument`
+
+ .. versionadded:: 0.0.4
+ """
+
[docs]classWarningLevel(Enum):
+ """Options for warning level in regard to likelihood of data loss.
+ """
+ IRREVERSIBLE=XABase.OSType("irrv")
+ NONE=XABase.OSType('none')
+ REVERSIBLE=XABase.OSType('rvbl')
+
+ def__init__(self,properties):
+ super().__init__(properties)
+ self.xa_wcls=XAAutomatorWindow
+
+ self.name:str#: The name of the application
+ self.frontmost:bool#: Whether Chromium is the active application
+ self.version:str#: The version of Chromium
+
+ @property
+ defname(self)->str:
+ returnself.xa_scel.name()
+
+ @property
+ deffrontmost(self)->bool:
+ returnself.xa_scel.frontmost()
+
+ @frontmost.setter
+ deffrontmost(self,frontmost:bool):
+ self.set_property('frontmost',frontmost)
+
+ @property
+ defversion(self)->str:
+ returnself.xa_scel.version()
+
+
[docs]defopen(self,path:Union[str,AppKit.NSURL])->'XAAutomatorWorkflow':
+ """Opens the file at the given filepath.
+
+ :param target: The path to a file or the URL to a website to open.
+ :type target: Union[str, AppKit.NSURL]
+ :return: A reference to the PyXA object that called this method.
+ :rtype: XAObject
+
+ .. versionadded:: 0.0.1
+ """
+ ifnotisinstance(path,AppKit.NSURL):
+ path=XABase.XAPath(path)
+ self.xa_wksp.openURLs_withAppBundleIdentifier_options_additionalEventParamDescriptor_launchIdentifiers_([path.xa_elem],self.xa_elem.bundleIdentifier(),0,None,None)
+ returnself.workflows()[0]
+
+
[docs]defadd(self,action:'XAAutomatorAction',workflow:'XAAutomatorWorkflow',index:int=-1)->'XAAutomatorApplication':
+ """Adds the specified action to a workflow at the specified index.
+
+ :param action: The action to add
+ :type action: XAAutomatorAction
+ :param workflow: The workflow to add the action to
+ :type workflow: XAAutomatorWorkflow
+ :param index: The index at which to add the action, defaults to -1
+ :type index: int, optional
+ :return: A reference to the application object
+ :rtype: XAAutomatorApplication
+
+ .. versionadded:: 0.0.4
+ """
+ self.xa_scel.add_to_atIndex_(action.xa_elem,workflow.xa_elem,index)
+ returnself
+
+
+
[docs]defdocuments(self,filter:Union[dict,None]=None)->'XAAutomatorDocumentList':
+ """Returns a list of documents, as PyXA objects, matching the given filter.
+
+ :param filter: Keys and values to filter documents by, defaults to None
+ :type filter: dict, optional
+ :return: A PyXA list object wrapping a list of documents
+ :rtype: XAAutomatorDocumentList
+
+ .. versionadded:: 0.0.4
+ """
+ returnself._new_element(self.xa_scel.documents(),XAAutomatorDocumentList,filter)
+
+
[docs]defautomator_actions(self,filter:Union[dict,None]=None)->'XAAutomatorActionList':
+ """Returns a list of Automator actions, as PyXA objects, matching the given filter.
+
+ :param filter: Keys and values to filter actions by, defaults to None
+ :type filter: dict, optional
+ :return: A PyXA list object wrapping a list of actions
+ :rtype: XAAutomatorActionList
+
+ .. versionadded:: 0.0.4
+ """
+ returnself._new_element(self.xa_scel.AutomatorActions(),XAAutomatorActionList,filter)
+
+
[docs]defvariables(self,filter:Union[dict,None]=None)->'XAAutomatorVariableList':
+ """Returns a list of Automator variables, as PyXA objects, matching the given filter.
+
+ :param filter: Keys and values to filter variables by, defaults to None
+ :type filter: dict, optional
+ :return: A PyXA list object wrapping a list of variables
+ :rtype: XAAutomatorVariableList
+
+ .. versionadded:: 0.0.4
+ """
+ returnself._new_element(self.xa_scel.variables(),XAAutomatorVariableList,filter)
+
+
[docs]defworkflows(self,filter:Union[dict,None]=None)->'XAAutomatorWorkflowList':
+ """Returns a list of Automator workflows, as PyXA objects, matching the given filter.
+
+ :param filter: Keys and values to filter workflows by, defaults to None
+ :type filter: dict, optional
+ :return: A PyXA list object wrapping a list of workflows
+ :rtype: XAAutomatorWorkflowList
+
+ .. versionadded:: 0.0.4
+ """
+ returnself._new_element(self.xa_scel.workflows(),XAAutomatorWorkflowList,filter)
+
+
[docs]defmake(self,specifier:str,properties:dict):
+ """Creates a new element of the given specifier class without adding it to any list.
+
+ Use :func:`XABase.XAList.push` to push the element onto a list.
+
+ :param specifier: The classname of the object to create
+ :type specifier: str
+ :param properties: The properties to give the object
+ :type properties: dict
+ :return: A PyXA wrapped form of the object
+ :rtype: XABase.XAObject
+
+ .. versionadded:: 0.0.4
+ """
+ obj=self.xa_scel.classForScriptingClass_(specifier).alloc().initWithProperties_(properties)
+
+ ifspecifier=="workflow":
+ if"path"notinpropertiesand"name"inproperties:
+ fm=AppKit.NSFileManager.defaultManager()
+ properties.update({"path":f"{fm.homeDirectoryForCurrentUser().path()}/Downloads/{properties.get('name')}.workflow"})
+ elifnotproperties.get("path").endswith(".workflow"):
+ properties.update({"path":properties.get("path")+".workflow"})
+
+ obj=self.xa_scel.classForScriptingClass_(specifier).alloc().initWithProperties_(properties)
+ returnself._new_element(obj,XAAutomatorWorkflow)
+ elifspecifier=="variable":
+ returnself._new_element(obj,XAAutomatorVariable)
+ elifspecifier=="document":
+ returnself._new_element(obj,XAAutomatorDocument)
+ elifspecifier=="action":
+ returnself._new_element(obj,XAAutomatorAction)
+ elifspecifier=="requiredResource":
+ returnself._new_element(obj,XAAutomatorRequiredResource)
+ elifspecifier=="setting":
+ returnself._new_element(obj,XAAutomatorSetting)
+
+
+
+
+
[docs]classXAAutomatorWindow(XABaseScriptable.XASBWindow):
+ """A class for managing and interacting with Automator windows.
+
+ .. seealso:: :class:`XAAutomatorApplication`
+
+ .. versionadded:: 0.0.4
+ """
+ def__init__(self,properties):
+ super().__init__(properties)
+ self.name:str#: The full title of the window
+ self.id:int#: The unique identifier for the window
+ self.index:int#: The index of the window in the front-to-back ordering
+ self.bounds:Tuple[int,int,int,int]#: The bounding rectangle of the window
+ self.floating:bool#: Whether the window float
+ self.modal:bool#: Whether the window is a modal window
+ self.closeable:bool#: Whether the window has a close button
+ self.miniaturizable:bool#: Whether the window can be minimized
+ self.miniaturized:bool#: Whether the window is currently minimized
+ self.resizable:bool#: Whether the window can be resized
+ self.visible:bool#: Whether the window is currently visible
+ self.zoomable:bool#: Whether the window can be zoomed
+ self.zoomed:bool#: Whether the window is currently zoomed
+ self.titled:bool#: Whether the window has a title bar
+ self.document:XAAutomatorDocument#: The document currently displayed in the window
+
+ @property
+ defname(self)->str:
+ returnself.xa_elem.name()
+
+ @name.setter
+ defname(self,name:str):
+ self.set_property("name",name)
+
+ @property
+ defid(self)->int:
+ returnself.xa_elem.id()
+
+ @property
+ defindex(self)->int:
+ returnself.xa_elem.index()
+
+ @index.setter
+ defindex(self,index:int):
+ self.set_property("index",index)
+
+ @property
+ defbounds(self)->Tuple[int,int,int,int]:
+ rect=self.xa_elem.bounds()
+ origin=rect.origin
+ size=rect.size
+ return(origin.x,origin.y,size.width,size.height)
+
+ @bounds.setter
+ defbounds(self,bounds:Tuple[int,int,int,int]):
+ x=bounds[0]
+ y=bounds[1]
+ w=bounds[2]
+ h=bounds[3]
+ value=AppKit.NSValue.valueWithRect_(AppKit.NSMakeRect(x,y,w,h))
+ self.set_property("bounds",value)
+
+ @property
+ deffloating(self)->bool:
+ returnself.xa_elem.floating()
+
+ @property
+ defmodal(self)->bool:
+ returnself.xa_elem.modal()
+
+ @property
+ defcloseable(self)->bool:
+ returnself.xa_elem.closeable()
+
+ @property
+ defminiaturizable(self)->bool:
+ returnself.xa_elem.miniaturizable()
+
+ @property
+ defminiaturized(self)->bool:
+ returnself.xa_elem.miniaturized()
+
+ @miniaturized.setter
+ defminiaturized(self,miniaturized:bool):
+ self.set_property("miniaturized",miniaturized)
+
+ @property
+ defresizable(self)->bool:
+ returnself.xa_elem.resizable()
+
+ @property
+ defvisible(self)->bool:
+ returnself.xa_elem.visible()
+
+ @visible.setter
+ defvisible(self,visible:bool):
+ self.set_property("visible",visible)
+
+ @property
+ defzoomable(self)->bool:
+ returnself.xa_elem.zoomable()
+
+ @property
+ defzoomed(self)->bool:
+ returnself.xa_elem.zoomed()
+
+ @zoomed.setter
+ defzoomed(self,zoomed:bool):
+ self.set_property("zoomed",zoomed)
+
+ @property
+ deftitled(self)->bool:
+ returnself.xa_elem.titled()
+
+ @property
+ defdocument(self)->'XAAutomatorDocument':
+ returnself._new_element(self.xa_elem.document(),XAAutomatorDocument)
+
+
+
+
+
[docs]classXAAutomatorDocumentList(XABase.XAList):
+ """A wrapper around a list of Automator documents which utilizes 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.
+
+ .. versionadded:: 0.0.4
+ """
+ def__init__(self,properties:dict,filter:Union[dict,None]=None):
+ super().__init__(properties,XAAutomatorDocument,filter)
+
+
[docs]defid(self)->List[int]:
+ """Retrieves the ID of each document in the list.
+
+ :return: The list of document IDs.
+ :rtype: List[int]
+
+ .. versionadded:: 0.0.4
+ """
+ returnlist(self.xa_elem.arrayByApplyingSelector_("id"))
+
+
[docs]deftitle(self)->List[str]:
+ """Retrieves the title of each document in the list.
+
+ :return: The list of document titles.
+ :rtype: List[str]
+
+ .. versionadded:: 0.0.4
+ """
+ returnlist(self.xa_elem.arrayByApplyingSelector_("title"))
+
+
[docs]defindex(self)->List[int]:
+ """Retrieves the index of each document in the list.
+
+ :return: The list of document indexes.
+ :rtype: List[int]
+
+ .. versionadded:: 0.0.4
+ """
+ returnlist(self.xa_elem.arrayByApplyingSelector_("index"))
+
+
[docs]defby_id(self,id:int)->Union['XAAutomatorDocument',None]:
+ """Retrieves the document whose ID matches the given ID, if one exists.
+
+ :return: The desired document, if it is found
+ :rtype: Union[XAAutomatorDocument, None]
+
+ .. versionadded:: 0.0.4
+ """
+ returnself.by_property("id",id)
+
+
[docs]defby_title(self,title:str)->Union['XAAutomatorDocument',None]:
+ """Retrieves the first document whose title matches the given title, if one exists.
+
+ :return: The desired document, if it is found
+ :rtype: Union[XAAutomatorDocument, None]
+
+ .. versionadded:: 0.0.4
+ """
+ returnself.by_property("title",title)
+
+
[docs]defby_index(self,index:int)->Union['XAAutomatorDocument',None]:
+ """Retrieves the document whose index matches the given index, if one exists.
+
+ :return: The desired document, if it is found
+ :rtype: Union[XAAutomatorDocument, None]
+
+ .. versionadded:: 0.0.4
+ """
+ returnself.by_property("index",index)
[docs]classXAAutomatorDocument(XABase.XAObject):
+ """A class for managing and interacting with Automator windows.
+
+ .. seealso:: :class:`XAAutomatorApplication`
+
+ .. versionadded:: 0.0.4
+ """
+ def__init__(self,properties):
+ super().__init__(properties)
+ self.modified:bool#: Whether the document has been modified since its last save
+ self.name:str#: The title of the document
+ self.path:str#: The path to the document on the disk
+
+ @property
+ defmodified(self)->bool:
+ returnself.xa_elem.modified()
+
+ @property
+ defname(self)->str:
+ returnself.xa_elem.name()
+
+ @name.setter
+ defname(self,name:str):
+ self.set_property("name",name)
+
+ @property
+ defpath(self)->XABase.XAPath:
+ returnXABase.XAPath(self.xa_elem.path())
+
+ @path.setter
+ defpath(self,path:Union[str,XABase.XAPath]):
+ ifisinstance(path,str):
+ path=XABase.XAPath(path)
+ self.set_property("path",path.path)
+
+ def__repr__(self):
+ return"<"+str(type(self))+self.name+">"
+
+
+
+
+
[docs]classXAAutomatorActionList(XABase.XAList):
+ """A wrapper around a list of Automator required resources which utilizes fast enumeration techniques.
+
+ All properties of required resources can be called as methods on the wrapped list, returning a list containing each resource's value for the property.
+
+ .. versionadded:: 0.0.4
+ """
+ def__init__(self,properties:dict,filter:Union[dict,None]=None):
+ super().__init__(properties,XAAutomatorAction,filter)
+
+
[docs]defbundle_id(self)->List[str]:
+ """Retrieves the bundle identifier of each action in the list.
+
+ :return: The list of bundle identifiers.
+ :rtype: List[str]
+
+ .. versionadded:: 0.0.4
+ """
+ returnlist(self.xa_elem.arrayByApplyingSelector_("bundleId"))
+
+
[docs]defcategory(self)->List[List[str]]:
+ """Retrieves the category/categories of each action in the list.
+
+ :return: The list of categories.
+ :rtype: List[List[str]]
+
+ .. versionadded:: 0.0.4
+ """
+ returnlist(self.xa_elem.arrayByApplyingSelector_("category"))
+
+
[docs]defcomment(self)->List[str]:
+ """Retrieves the comments of each action in the list.
+
+ :return: The list of comments.
+ :rtype: List[str]
+
+ .. versionadded:: 0.0.4
+ """
+ returnlist(self.xa_elem.arrayByApplyingSelector_("comment"))
+
+
[docs]defenabled(self)->List[bool]:
+ """Retrieves the enabled status of each action in the list.
+
+ :return: The list of enabled status booleans.
+ :rtype: List[bool]
+
+ .. versionadded:: 0.0.4
+ """
+ returnlist(self.xa_elem.arrayByApplyingSelector_("enabled"))
+
+
[docs]defexecution_error_message(self)->List[str]:
+ """Retrieves the execution error message of each action in the list.
+
+ :return: The list of error messages.
+ :rtype: List[str]
+
+ .. versionadded:: 0.0.4
+ """
+ returnlist(self.xa_elem.arrayByApplyingSelector_("executionErrorMessage"))
+
+
[docs]defexecution_error_number(self)->List[int]:
+ """Retrieves the execution error number of each action in the list.
+
+ :return: The list of error numbers.
+ :rtype: List[int]
+
+ .. versionadded:: 0.0.4
+ """
+ returnlist(self.xa_elem.arrayByApplyingSelector_("executionErrorNumber"))
+
+
[docs]defexecution_result(self)->List[Any]:
+ """Retrieves the result value of each action in the list.
+
+ :return: The list of results.
+ :rtype: List[Any]
+
+ .. versionadded:: 0.0.4
+ """
+ returnlist(self.xa_elem.arrayByApplyingSelector_("executionResult"))
+
+
[docs]deficon_name(self)->List[str]:
+ """Retrieves the icon name of each action in the list.
+
+ :return: The list of icon names.
+ :rtype: List[str]
+
+ .. versionadded:: 0.0.4
+ """
+ returnlist(self.xa_elem.arrayByApplyingSelector_("iconName"))
+
+
[docs]defignores_input(self)->List[bool]:
+ """Retrieves the ignore input status of each action in the list.
+
+ :return: The list of ignore input status booleans.
+ :rtype: List[bool]
+
+ .. versionadded:: 0.0.4
+ """
+ returnlist(self.xa_elem.arrayByApplyingSelector_("ignoresInput"))
+
+
[docs]defindex(self)->List[int]:
+ """Retrieves the index of each action in the list.
+
+ :return: The list of action indices.
+ :rtype: List[int]
+
+ .. versionadded:: 0.0.4
+ """
+ returnlist(self.xa_elem.arrayByApplyingSelector_("index"))
+
+
[docs]definput_types(self)->List[List[str]]:
+ """Retrieves the input types of each action in the list.
+
+ :return: The list of input types.
+ :rtype: List[List[str]]
+
+ .. versionadded:: 0.0.4
+ """
+ returnlist(self.xa_elem.arrayByApplyingSelector_("inputTypes"))
+
+
[docs]defkeywords(self)->List[List[str]]:
+ """Retrieves the keywords of each action in the list.
+
+ :return: The list of keywords.
+ :rtype: List[List[str]]
+
+ .. versionadded:: 0.0.4
+ """
+ returnlist(self.xa_elem.arrayByApplyingSelector_("keywords"))
+
+
[docs]defname(self)->List[str]:
+ """Retrieves the name of each action in the list.
+
+ :return: The list of names.
+ :rtype: List[str]
+
+ .. versionadded:: 0.0.4
+ """
+ returnlist(self.xa_elem.arrayByApplyingSelector_("name"))
+
+
[docs]defoutput_types(self)->List[List[str]]:
+ """Retrieves the output types of each action in the list.
+
+ :return: The list of output types.
+ :rtype: List[List[str]]
+
+ .. versionadded:: 0.0.4
+ """
+ returnlist(self.xa_elem.arrayByApplyingSelector_("outputTypes"))
+
+
[docs]defparent_workflow(self)->'XAAutomatorWorkflowList':
+ """Retrieves the parent workflow of each action in the list.
+
+ :return: The list of parent workflows.
+ :rtype: XAAutomatorWorkflowList
+
+ .. versionadded:: 0.0.4
+ """
+ ls=self.xa_elem.arrayByApplyingSelector_("parentWorkflow")
+ returnself._new_element(ls,XAAutomatorWorkflowList)
+
+
[docs]defpath(self)->List[str]:
+ """Retrieves the file path of each action in the list.
+
+ :return: The list of paths.
+ :rtype: List[str]
+
+ .. versionadded:: 0.0.4
+ """
+ returnlist(self.xa_elem.arrayByApplyingSelector_("path"))
+
+
[docs]defshow_action_when_run(self)->List[bool]:
+ """Retrieves the status of the show action when run setting of each action in the list.
+
+ :return: The list of boolean statuses.
+ :rtype: List[bool]
+
+ .. versionadded:: 0.0.4
+ """
+ returnlist(self.xa_elem.arrayByApplyingSelector_("showActionWhenRun"))
+
+
[docs]deftarget_application(self)->List[List[str]]:
+ """Retrieves the target application name of each action in the list.
+
+ :return: The list of target application names.
+ :rtype: List[List[str]]
+
+ .. versionadded:: 0.0.4
+ """
+ returnlist(self.xa_elem.arrayByApplyingSelector_("targetApplication"))
+
+
[docs]defversion(self)->List[str]:
+ """Retrieves the version of each action in the list.
+
+ :return: The list of versions.
+ :rtype: List[str]
+
+ .. versionadded:: 0.0.4
+ """
+ returnlist(self.xa_elem.arrayByApplyingSelector_("version"))
+
+
[docs]defwarning_action(self)->List[str]:
+ """Retrieves the warning action of each action in the list.
+
+ :return: The list of warning actions.
+ :rtype: List[str]
+
+ .. versionadded:: 0.0.4
+ """
+ returnlist(self.xa_elem.arrayByApplyingSelector_("warningAction"))
+
+
[docs]defwarning_level(self)->List[XAAutomatorApplication.WarningLevel]:
+ """Retrieves the warning level of each action in the list.
+
+ :return: The list of warning levels.
+ :rtype: List[XAAutomatorApplication.WarningLevel]
+
+ .. versionadded:: 0.0.4
+ """
+ ls=self.xa_elem.arrayByApplyingSelector_("warningLevel")
+ return[XAAutomatorApplication.WarningLevel(x)forxinls]
+
+
[docs]defwarning_message(self)->List[str]:
+ """Retrieves the warning message of each action in the list.
+
+ :return: The list of warning messages.
+ :rtype: List[str]
+
+ .. versionadded:: 0.0.4
+ """
+ returnlist(self.xa_elem.arrayByApplyingSelector_("warningMessage"))
+
+
[docs]defby_bundle_id(self,bundle_id:str)->Union['XAAutomatorAction',None]:
+ """Retrieves the first action whose bundle identifier matches the given identifier, if one exists.
+
+ :return: The desired action, if it is found
+ :rtype: Union[XAAutomatorAction, None]
+
+ .. versionadded:: 0.0.4
+ """
+ returnself.by_property("bundleId",bundle_id)
+
+
[docs]defby_category(self,category:List[str])->Union['XAAutomatorAction',None]:
+ """Retrieves the first action whose category matches the given category, if one exists.
+
+ :return: The desired action, if it is found
+ :rtype: Union[XAAutomatorAction, None]
+
+ .. versionadded:: 0.0.4
+ """
+ returnself.by_property("category",category)
+
+
[docs]defby_comment(self,comment:str)->Union['XAAutomatorAction',None]:
+ """Retrieves the first action whose comment matches the given comment, if one exists.
+
+ :return: The desired action, if it is found
+ :rtype: Union[XAAutomatorAction, None]
+
+ .. versionadded:: 0.0.4
+ """
+ returnself.by_property("comment",comment)
+
+
[docs]defby_enabled(self,enabled:bool)->Union['XAAutomatorAction',None]:
+ """Retrieves the first action whose enabled status matches the given boolean value, if one exists.
+
+ :return: The desired action, if it is found
+ :rtype: Union[XAAutomatorAction, None]
+
+ .. versionadded:: 0.0.4
+ """
+ returnself.by_property("enabled",enabled)
+
+
[docs]defby_execution_error_message(self,execution_error_message:str)->Union['XAAutomatorAction',None]:
+ """Retrieves the first action whose error message matches the given message, if one exists.
+
+ :return: The desired action, if it is found
+ :rtype: Union[XAAutomatorAction, None]
+
+ .. versionadded:: 0.0.4
+ """
+ returnself.by_property("executionErrorMessage",execution_error_message)
+
+
[docs]defby_execution_error_number(self,execution_error_number:int)->Union['XAAutomatorAction',None]:
+ """Retrieves the first action whose error number matches the given error number, if one exists.
+
+ :return: The desired action, if it is found
+ :rtype: Union[XAAutomatorAction, None]
+
+ .. versionadded:: 0.0.4
+ """
+ returnself.by_property("executionErrorNumber",execution_error_number)
+
+
[docs]defby_execution_result(self,execution_result:Any)->Union['XAAutomatorAction',None]:
+ """Retrieves the first action whose execution result matches the given value, if one exists.
+
+ :return: The desired action, if it is found
+ :rtype: Union[XAAutomatorAction, None]
+
+ .. versionadded:: 0.0.4
+ """
+ returnself.by_property("executionResult",execution_result)
+
+
[docs]defby_icon_name(self,icon_name:str)->Union['XAAutomatorAction',None]:
+ """Retrieves the first action whose icon name matches the given name, if one exists.
+
+ :return: The desired action, if it is found
+ :rtype: Union[XAAutomatorAction, None]
+
+ .. versionadded:: 0.0.4
+ """
+ returnself.by_property("iconName",icon_name)
+
+
[docs]defby_id(self,id:str)->Union['XAAutomatorAction',None]:
+ """Retrieves the action whose ID matches the given ID, if one exists.
+
+ :return: The desired action, if it is found
+ :rtype: Union[XAAutomatorAction, None]
+
+ .. versionadded:: 0.0.4
+ """
+ returnself.by_property("id",id)
+
+
[docs]defby_ignores_input(self,ignores_input:bool)->Union['XAAutomatorAction',None]:
+ """Retrieves the first action whose ignore input status matches the given boolean value, if one exists.
+
+ :return: The desired action, if it is found
+ :rtype: Union[XAAutomatorAction, None]
+
+ .. versionadded:: 0.0.4
+ """
+ returnself.by_property("ignoresInput",ignores_input)
+
+
[docs]defby_input_types(self,input_types:List[str])->Union['XAAutomatorAction',None]:
+ """Retrieves the first action whose input types match the given input types, if one exists.
+
+ :return: The desired action, if it is found
+ :rtype: Union[XAAutomatorAction, None]
+
+ .. versionadded:: 0.0.4
+ """
+ returnself.by_property("inputTypes",input_types)
+
+
[docs]defby_keywords(self,keywords:List[str])->Union['XAAutomatorAction',None]:
+ """Retrieves the first action whose keywords match the given keywords, if one exists.
+
+ :return: The desired action, if it is found
+ :rtype: Union[XAAutomatorAction, None]
+
+ .. versionadded:: 0.0.4
+ """
+ returnself.by_property("keywords",keywords)
+
+
[docs]defby_name(self,name:str)->Union['XAAutomatorAction',None]:
+ """Retrieves the first action whose name matches the given name, if one exists.
+
+ :return: The desired action, if it is found
+ :rtype: Union[XAAutomatorAction, None]
+
+ .. versionadded:: 0.0.4
+ """
+ returnself.by_property("name",name)
+
+
[docs]defby_output_types(self,output_types:List[str])->Union['XAAutomatorAction',None]:
+ """Retrieves the first action whose output types match the given output types, if one exists.
+
+ :return: The desired action, if it is found
+ :rtype: Union[XAAutomatorAction, None]
+
+ .. versionadded:: 0.0.4
+ """
+ returnself.by_property("outputTypes",output_types)
+
+
[docs]defby_parent_workflow(self,parent_workflow:'XAAutomatorWorkflow')->Union['XAAutomatorAction',None]:
+ """Retrieves the first action whose parent workflow matches the given workflow, if one exists.
+
+ :return: The desired action, if it is found
+ :rtype: Union[XAAutomatorAction, None]
+
+ .. versionadded:: 0.0.4
+ """
+ returnself.by_property("parentWorkflow",parent_workflow.xa_elem)
+
+
[docs]defby_path(self,path:str)->Union['XAAutomatorAction',None]:
+ """Retrieves the first action whose path matches the given path, if one exists.
+
+ :return: The desired action, if it is found
+ :rtype: Union[XAAutomatorAction, None]
+
+ .. versionadded:: 0.0.4
+ """
+ returnself.by_property("path",path)
+
+
[docs]defby_show_action_when_run(self,show_action_when_run:bool)->Union['XAAutomatorAction',None]:
+ """Retrieves the first action whose show action when run status matches the given boolean value, if one exists.
+
+ :return: The desired action, if it is found
+ :rtype: Union[XAAutomatorAction, None]
+
+ .. versionadded:: 0.0.4
+ """
+ returnself.by_property("show_action_when_run",show_action_when_run)
+
+
[docs]defby_target_application(self,target_application:List[str])->Union['XAAutomatorAction',None]:
+ """Retrieves the first action whose target application matches the given application name, if one exists.
+
+ :return: The desired action, if it is found
+ :rtype: Union[XAAutomatorAction, None]
+
+ .. versionadded:: 0.0.4
+ """
+ returnself.by_property("targetApplication",target_application)
+
+
[docs]defby_version(self,version:str)->Union['XAAutomatorAction',None]:
+ """Retrieves the first action whose version matches the given version, if one exists.
+
+ :return: The desired action, if it is found
+ :rtype: Union[XAAutomatorAction, None]
+
+ .. versionadded:: 0.0.4
+ """
+ returnself.by_property("version",version)
+
+
[docs]defby_warning_action(self,warning_action:str)->Union['XAAutomatorAction',None]:
+ """Retrieves the first action whose warning action matches the given action, if one exists.
+
+ :return: The desired action, if it is found
+ :rtype: Union[XAAutomatorAction, None]
+
+ .. versionadded:: 0.0.4
+ """
+ returnself.by_property("warningAction",warning_action)
+
+
[docs]defby_warning_level(self,warning_level:XAAutomatorApplication.WarningLevel)->Union['XAAutomatorAction',None]:
+ """Retrieves the first action whose warning level matches the given warning level, if one exists.
+
+ :return: The desired action, if it is found
+ :rtype: Union[XAAutomatorAction, None]
+
+ .. versionadded:: 0.0.4
+ """
+ returnself.by_property("warningLevel",warning_level.value)
+
+
[docs]defby_warning_message(self,warning_message:str)->Union['XAAutomatorAction',None]:
+ """Retrieves the first action whose warning message matches the given message, if one exists.
+
+ :return: The desired action, if it is found
+ :rtype: Union[XAAutomatorAction, None]
+
+ .. versionadded:: 0.0.4
+ """
+ returnself.by_property("warningMessage",warning_message)
[docs]classXAAutomatorAction(XABase.XAObject):
+ """A class for managing and interacting with actions in Automator.app.
+
+ .. seealso:: :class:`XAAutomatorApplication`
+
+ .. versionadded:: 0.0.4
+ """
+ def__init__(self,properties):
+ super().__init__(properties)
+ self.bundle_id:str#: The bundle identifier for the action
+ self.category:List[str]#: The category that contains the action
+ self.comment:str#: The comment for the name of the action
+ self.enabled:bool#: Whether the action is enabled
+ self.execution_error_message:str#: The text error message generated by execution of the action
+ self.execution_error_number:int#: The numeric error code generated by execution of the action
+ self.execution_result:Any#: The result of the action, passed as input to the next action
+ self.icon_name:str#: The name for the icon associated with the action
+ self.id:str#: The unique identifier for the action
+ self.ignores_input:bool#: Whether the action ignores input when run
+ self.index:int#: The index of the action from the first action in the workflow
+ self.input_types:List[str]#: The input types accepted by the action
+ self.keywords:List[str]#: The keywords that describe the action
+ self.name:str#: The localized name of the action
+ self.output_types:List[str]#: The output types produces by the action
+ self.parent_workflow:XAAutomatorWorkflow#: The workflow that contains the action
+ self.path:str#: The path of the file that contains the action
+ self.show_action_when_run:bool#: Whether the action should show its user interface when run
+ self.target_application:List[str]#: The application(s) with which the action communicates
+ self.version:str#: The version of the action
+ self.warning_action:str#: The action suggested by the warning, if any
+ self.warning_level:XAAutomatorApplication.WarningLevel#: The level of the warning, increasing in likelihood of data loss
+ self.warning_message:str#: The message that accompanies the warning, if any
+
+ @property
+ defbundle_id(self)->str:
+ returnself.xa_elem.bundleId()
+
+ @property
+ defcategory(self)->List[str]:
+ returnself.xa_elem.category()
+
+ @property
+ defcomment(self)->str:
+ returnself.xa_elem.comment()
+
+ @comment.setter
+ defcomment(self,comment:str):
+ self.set_property("comment",comment)
+
+ @property
+ defenabled(self)->bool:
+ returnself.xa_elem.enabled()
+
+ @enabled.setter
+ defenabled(self,enabled:bool):
+ self.set_property("enabled",enabled)
+
+ @property
+ defexecution_error_message(self)->str:
+ returnself.xa_elem.executionErrorMessage()
+
+ @property
+ defexecution_error_number(self)->int:
+ returnself.xa_elem.executionErrorNumber()
+
+ @property
+ defexecution_result(self)->Any:
+ returnself.xa_elem.executionResult()
+
+ @property
+ deficon_name(self)->str:
+ returnself.xa_elem.iconName()
+
+ @property
+ defid(self)->str:
+ returnself.xa_elem.id()
+
+ @property
+ defignores_input(self)->bool:
+ returnself.xa_elem.ignoresInput()
+
+ @ignores_input.setter
+ defignores_input(self,ignores_input:bool):
+ self.set_property("ignoresInput",ignores_input)
+
+ @property
+ defindex(self)->int:
+ returnself.xa_elem.index()
+
+ @index.setter
+ defindex(self,index:int):
+ self.set_property("index",index)
+
+ @property
+ definput_types(self)->List[str]:
+ returnself.xa_elem.inputTypes()
+
+ @property
+ defkeywords(self)->List[str]:
+ returnself.xa_elem.keywords()
+
+ @property
+ defname(self)->str:
+ returnself.xa_elem.name()
+
+ @property
+ defoutput_types(self)->List[str]:
+ returnself.xa_elem.outputTypes()
+
+ @property
+ defparent_workflow(self)->'XAAutomatorWorkflow':
+ returnself._new_element(self.xa_elem.parentWorkflow(),XAAutomatorWorkflow)
+
+ @property
+ defpath(self)->XABase.XAPath:
+ returnXABase.XAPath(self.xa_elem.path())
+
+ @property
+ defshow_action_when_run(self)->bool:
+ returnself.xa_elem.showActionWehnRun()
+
+ @show_action_when_run.setter
+ defshow_action_when_run(self,show_action_when_run:bool):
+ self.set_property("showActionWhenRun",show_action_when_run)
+
+ @property
+ deftarget_application(self)->List[str]:
+ returnself.xa_elem.targetApplication()
+
+ @property
+ defversion(self)->str:
+ returnself.xa_elem.version()
+
+ @property
+ defwarning_action(self)->str:
+ returnself.xa_elem.warningAction()
+
+ @property
+ defwarning_level(self)->XAAutomatorApplication.WarningLevel:
+ returnXAAutomatorApplication.WarningLevel(self.xa_elem.warningLevel())
+
+ @property
+ defwarning_message(self)->str:
+ returnself.xa_elem.warningMessage()
+
+
[docs]defrequired_resources(self,filter:Union[dict,None]=None)->'XAAutomatorRequiredResourceList':
+ """Returns a list of required resource, as PyXA objects, matching the given filter.
+
+ :param filter: Keys and values to filter resources by, defaults to None
+ :type filter: dict, optional
+ :return: A PyXA list object wrapping a list of required resources
+ :rtype: XAAutomatorVariableList
+
+ .. versionadded:: 0.0.4
+ """
+ returnself._new_element(self.xa_elem.requiredResources(),XAAutomatorRequiredResourceList,filter)
+
+
[docs]defsettings(self,filter:Union[dict,None]=None)->'XAAutomatorSettingList':
+ """Returns a list of settings, as PyXA objects, matching the given filter.
+
+ :param filter: Keys and values to filter settings by, defaults to None
+ :type filter: dict, optional
+ :return: A PyXA list object wrapping a list of settings
+ :rtype: XAAutomatorWorkflowList
+
+ .. versionadded:: 0.0.4
+ """
+ returnself._new_element(self.xa_elem.settings(),XAAutomatorSettingList,filter)
[docs]classXAAutomatorRequiredResourceList(XABase.XAList):
+ """A wrapper around a list of Automator required resources which utilizes fast enumeration techniques.
+
+ All properties of required resources can be called as methods on the wrapped list, returning a list containing each resource's value for the property.
+
+ .. versionadded:: 0.0.4
+ """
+ def__init__(self,properties:dict,filter:Union[dict,None]=None):
+ super().__init__(properties,XAAutomatorRequiredResource,filter)
+
+
[docs]defkind(self)->List[str]:
+ """Retrieves the resource type of each resource in the list.
+
+ :return: The list of resource types.
+ :rtype: List[str]
+
+ .. versionadded:: 0.0.4
+ """
+ returnlist(self.xa_elem.arrayByApplyingSelector_("kind"))
+
+
[docs]defname(self)->List[str]:
+ """Retrieves the name of each resource in the list.
+
+ :return: The list of resource names.
+ :rtype: List[str]
+
+ .. versionadded:: 0.0.4
+ """
+ returnlist(self.xa_elem.arrayByApplyingSelector_("name"))
+
+
[docs]defresource(self)->List[str]:
+ """Retrieves the specification of each resource in the list.
+
+ :return: The list of resource specifications.
+ :rtype: List[str]
+
+ .. versionadded:: 0.0.4
+ """
+ returnlist(self.xa_elem.arrayByApplyingSelector_("resource"))
+
+
[docs]defversion(self)->List[int]:
+ """Retrieves the version of each resource in the list.
+
+ :return: The list of resource versions.
+ :rtype: List[int]
+
+ .. versionadded:: 0.0.4
+ """
+ returnlist(self.xa_elem.arrayByApplyingSelector_("version"))
+
+
[docs]defby_kind(self,kind:str)->Union['XAAutomatorRequiredResource',None]:
+ """Retrieves the first resource whose kind matches the given kind, if one exists.
+
+ :return: The desired resource, if it is found
+ :rtype: Union[XAAutomatorRequiredResource, None]
+
+ .. versionadded:: 0.0.4
+ """
+ returnself.by_property("kind",kind)
+
+
[docs]defby_name(self,name:str)->Union['XAAutomatorRequiredResource',None]:
+ """Retrieves the first resource whose name matches the given name, if one exists.
+
+ :return: The desired resource, if it is found
+ :rtype: Union[XAAutomatorRequiredResource, None]
+
+ .. versionadded:: 0.0.4
+ """
+ returnself.by_property("name",name)
+
+
[docs]defby_resource(self,resource:str)->Union['XAAutomatorRequiredResource',None]:
+ """Retrieves the first resource whose specification matches the given specification, if one exists.
+
+ :return: The desired resource, if it is found
+ :rtype: Union[XAAutomatorRequiredResource, None]
+
+ .. versionadded:: 0.0.4
+ """
+ returnself.by_property("resource",resource)
+
+
[docs]defby_version(self,version:int)->Union['XAAutomatorRequiredResource',None]:
+ """Retrieves the first resource whose version matches the given version, if one exists.
+
+ :return: The desired resource, if it is found
+ :rtype: Union[XAAutomatorRequiredResource, None]
+
+ .. versionadded:: 0.0.4
+ """
+ returnself.by_property("version",version)
[docs]classXAAutomatorRequiredResource(XABase.XAObject):
+ """A class for managing and interacting with required resources in Automator.app.
+
+ .. seealso:: :class:`XAAutomatorApplication`
+
+ .. versionadded:: 0.0.4
+ """
+ def__init__(self,properties):
+ super().__init__(properties)
+ self.kind:str#: The kind of required resource
+ self.name:str#: The name of the required resource
+ self.resource:str#: The specification of the required resource
+ self.version:int#: The minimum acceptable version of the required resource
+
+ @property
+ defkind(self)->str:
+ returnself.xa_elem.kind()
+
+ @property
+ defname(self)->str:
+ returnself.xa_elem.name()
+
+ @property
+ defresource(self)->str:
+ returnself.xa_elem.resource()
+
+ @property
+ defversion(self)->int:
+ returnself.xa_elem.version()
+
+ def__repr__(self):
+ return"<"+str(type(self))+self.name+">"
+
+
+
+
+
[docs]classXAAutomatorSettingList(XABase.XAList):
+ """A wrapper around a list of Automator settings which utilizes fast enumeration techniques.
+
+ All properties of settings can be called as methods on the wrapped list, returning a list containing each setting's value for the property.
+
+ .. versionadded:: 0.0.4
+ """
+ def__init__(self,properties:dict,filter:Union[dict,None]=None):
+ super().__init__(properties,XAAutomatorSetting,filter)
+
+
[docs]defdefault_value(self)->List[Any]:
+ """Retrieves the default value of each setting in the list.
+
+ :return: The list of default values.
+ :rtype: List[Any]
+
+ .. versionadded:: 0.0.4
+ """
+ returnlist(self.xa_elem.arrayByApplyingSelector_("defaultValue"))
+
+
[docs]defname(self)->List[str]:
+ """Retrieves the name of each setting in the list.
+
+ :return: The list of setting names.
+ :rtype: List[str]
+
+ .. versionadded:: 0.0.4
+ """
+ returnlist(self.xa_elem.arrayByApplyingSelector_("name"))
+
+
[docs]defvalue(self)->List[Any]:
+ """Retrieves the current value of each setting in the list.
+
+ :return: The list of current values.
+ :rtype: List[Any]
+
+ .. versionadded:: 0.0.4
+ """
+ returnlist(self.xa_elem.arrayByApplyingSelector_("value"))
+
+
[docs]defby_default_value(self,default_value:Any)->Union['XAAutomatorSetting',None]:
+ """Retrieves the first setting whose default value matches the given value, if one exists.
+
+ :return: The desired setting, if it is found
+ :rtype: Union[XAAutomatorSetting, None]
+
+ .. versionadded:: 0.0.4
+ """
+ ifisinstance(default_value,XABase.XAObject):
+ default_value=default_value.xa_elem
+ returnself.by_property("defaultValue",default_value)
+
+
[docs]defby_name(self,name:str)->Union['XAAutomatorSetting',None]:
+ """Retrieves the first setting whose name matches the given name, if one exists.
+
+ :return: The desired setting, if it is found
+ :rtype: Union[XAAutomatorSetting, None]
+
+ .. versionadded:: 0.0.4
+ """
+ returnself.by_property("name",name)
+
+
[docs]defby_value(self,value:Any)->Union['XAAutomatorSetting',None]:
+ """Retrieves the first setting whose current value matches the given value, if one exists.
+
+ :return: The desired setting, if it is found
+ :rtype: Union[XAAutomatorSetting, None]
+
+ .. versionadded:: 0.0.4
+ """
+ ifisinstance(value,XABase.XAObject):
+ value=value.xa_elem
+ returnself.by_property("value",value)
[docs]classXAAutomatorSetting(XABase.XAObject):
+ """A class for managing and interacting with Automator settings (i.e. named values).
+
+ .. seealso:: :class:`XAAutomatorApplication`
+
+ .. versionadded:: 0.0.4
+ """
+ def__init__(self,properties):
+ super().__init__(properties)
+ self.default_value:Any#: The default value of the setting
+ self.name:str#: The name of the setting
+ self.value:Any#: The value of the setting
+
+ @property
+ defdefault_value(self)->Any:
+ returnself.xa_elem.defaultValue()
+
+ @property
+ defname(self)->str:
+ returnself.xa_elem.name()
+
+ @property
+ defvalue(self)->Any:
+ returnself.xa_elem.value()
+
+ @value.setter
+ defvalue(self,value:Any):
+ self.set_property("value",value)
+
+ def__repr__(self):
+ return"<"+str(type(self))+self.name+">"
+
+
+
+
+
[docs]classXAAutomatorVariableList(XABase.XAList):
+ """A wrapper around a list of Automator variables which utilizes fast enumeration techniques.
+
+ All properties of variables can be called as methods on the wrapped list, returning a list containing each variable's value for the property.
+
+ .. versionadded:: 0.0.4
+ """
+ def__init__(self,properties:dict,filter:Union[dict,None]=None):
+ super().__init__(properties,XAAutomatorVariable,filter)
+
+
[docs]defname(self)->List[str]:
+ """Retrieves the name of each variable in the list.
+
+ :return: The list of variable names.
+ :rtype: List[Any]
+
+ .. versionadded:: 0.0.4
+ """
+ returnlist(self.xa_elem.arrayByApplyingSelector_("name"))
+
+
[docs]defsettable(self)->List[bool]:
+ """Retrieves the value of the settable attribute of each variable in the list.
+
+ :return: The list of settable status booleans.
+ :rtype: List[bool]
+
+ .. versionadded:: 0.0.4
+ """
+ returnlist(self.xa_elem.arrayByApplyingSelector_("settable"))
+
+
[docs]defvalue(self)->List[Any]:
+ """Retrieves the current value of each variable in the list.
+
+ :return: The list of current values.
+ :rtype: List[Any]
+
+ .. versionadded:: 0.0.4
+ """
+ returnlist(self.xa_elem.arrayByApplyingSelector_("value"))
+
+
[docs]defby_name(self,name:str)->Union['XAAutomatorVariable',None]:
+ """Retrieves the first variable whose name matches the given name, if one exists.
+
+ :return: The desired variable, if it is found
+ :rtype: Union[XAAutomatorVariable, None]
+
+ .. versionadded:: 0.0.4
+ """
+ returnself.by_property("name",name)
+
+
[docs]defby_settable(self,settable:bool)->Union['XAAutomatorVariable',None]:
+ """Retrieves the first variable whose settable status matches the given boolean, if one exists.
+
+ :return: The desired variable, if it is found
+ :rtype: Union[XAAutomatorVariable, None]
+
+ .. versionadded:: 0.0.4
+ """
+ returnself.by_property("settable",settable)
+
+
[docs]defby_value(self,value:Any)->Union['XAAutomatorVariable',None]:
+ """Retrieves the first variable whose current value matches the given value, if one exists.
+
+ :return: The desired variable, if it is found
+ :rtype: Union[XAAutomatorVariable, None]
+
+ .. versionadded:: 0.0.4
+ """
+ ifisinstance(value,XABase.XAObject):
+ value=value.xa_elem
+ returnself.by_property("value",value)
[docs]classXAAutomatorVariable(XABase.XAObject):
+ """A class for managing and interacting with Automator variables.
+
+ .. seealso:: :class:`XAAutomatorApplication`
+
+ .. versionadded:: 0.0.4
+ """
+ def__init__(self,properties):
+ super().__init__(properties)
+ self.name:str#: The name of the variable
+ self.settable:bool#: Whether the name and value of the variable can be changed
+ self.value:Any#: The value of the variable
+
+ @property
+ defname(self)->str:
+ returnself.xa_elem.name()
+
+ @name.setter
+ defname(self,name:str):
+ self.set_property("name",name)
+
+ @property
+ defsettable(self)->bool:
+ returnself.xa_elem.settable()
+
+ @property
+ defvalue(self)->Any:
+ returnself.xa_elem.value()
+
+ @value.setter
+ defvalue(self,value:Any):
+ self.set_property("value",value)
+
+ def__repr__(self):
+ return"<"+str(type(self))+self.name+">"
+
+
+
+
+
[docs]classXAAutomatorWorkflowList(XABase.XAList):
+ """A wrapper around a list of Automator workflows which utilizes fast enumeration techniques.
+
+ All properties of workflows can be called as methods on the wrapped list, returning a list containing each workflow's value for the property.
+
+ .. versionadded:: 0.0.4
+ """
+ def__init__(self,properties:dict,filter:Union[dict,None]=None):
+ super().__init__(properties,XAAutomatorWorkflow,filter)
+
+
[docs]defcurrent_action(self)->XAAutomatorActionList:
+ """Retrieves the current action of each workflow in the list.
+
+ :return: The list of current actions.
+ :rtype: XAAutomatorActionList
+
+ .. versionadded:: 0.0.4
+ """
+ ls=self.xa_elem.arrayByApplyingSelector_("currentAction")
+ returnself._new_element(ls,XAAutomatorActionList)
+
+
[docs]defexecution_error_message(self)->List[str]:
+ """Retrieves the execution error message of each workflow in the list.
+
+ :return: The list of error messages.
+ :rtype: List[str]
+
+ .. versionadded:: 0.0.4
+ """
+ returnlist(self.xa_elem.arrayByApplyingSelector_("executionErrorMessage"))
+
+
[docs]defexecution_error_number(self)->List[int]:
+ """Retrieves the execution error numbers of each workflow in the list.
+
+ :return: The list of error numbers.
+ :rtype: List[int]
+
+ .. versionadded:: 0.0.4
+ """
+ returnlist(self.xa_elem.arrayByApplyingSelector_("executionErrorNumber"))
+
+
[docs]defexecution_id(self)->List[str]:
+ """Retrieves the execution ID of each workflow in the list.
+
+ :return: The list of execution IDs.
+ :rtype: List[str]
+
+ .. versionadded:: 0.0.4
+ """
+ returnlist(self.xa_elem.arrayByApplyingSelector_("executionId"))
+
+
[docs]defexecution_result(self)->List[Any]:
+ """Retrieves the execution result of each workflow in the list.
+
+ :return: The list of results.
+ :rtype: List[Any]
+
+ .. versionadded:: 0.0.4
+ """
+ returnlist(self.xa_elem.arrayByApplyingSelector_("executionResult"))
+
+
[docs]defname(self)->List[str]:
+ """Retrieves the name of each workflow in the list.
+
+ :return: The list of workflow names.
+ :rtype: List[str]
+
+ .. versionadded:: 0.0.4
+ """
+ returnlist(self.xa_elem.arrayByApplyingSelector_("name"))
+
+
[docs]defby_current_action(self,current_action:XAAutomatorAction)->Union['XAAutomatorWorkflow',None]:
+ """Retrieves the first workflow whose current action matches the given action, if one exists.
+
+ :return: The desired workflow, if it is found
+ :rtype: Union[XAAutomatorWorkflow, None]
+
+ .. versionadded:: 0.0.4
+ """
+ returnself.by_property("currentAction",current_action.xa_elem)
+
+
[docs]defby_execution_error_message(self,execution_error_message:str)->Union['XAAutomatorWorkflow',None]:
+ """Retrieves the first workflow whose error message matches the given message, if one exists.
+
+ :return: The desired workflow, if it is found
+ :rtype: Union[XAAutomatorWorkflow, None]
+
+ .. versionadded:: 0.0.4
+ """
+ returnself.by_property("executionErrorMessage",execution_error_message)
+
+
[docs]defby_execution_error_number(self,execution_error_number:int)->Union['XAAutomatorWorkflow',None]:
+ """Retrieves the first workflow whose error number matches the given error number, if one exists.
+
+ :return: The desired workflow, if it is found
+ :rtype: Union[XAAutomatorWorkflow, None]
+
+ .. versionadded:: 0.0.4
+ """
+ returnself.by_property("executionErrorNumber",execution_error_number)
+
+
[docs]defby_execution_id(self,execution_id:str)->Union['XAAutomatorWorkflow',None]:
+ """Retrieves the workflow whose execution ID matches the given ID, if one exists.
+
+ :return: The desired workflow, if it is found
+ :rtype: Union[XAAutomatorWorkflow, None]
+
+ .. versionadded:: 0.0.4
+ """
+ returnself.by_property("executionId",execution_id)
+
+
[docs]defby_execution_result(self,result:Any)->Union['XAAutomatorWorkflow',None]:
+ """Retrieves the first workflow whose execution result matches the given value, if one exists.
+
+ :return: The desired workflow, if it is found
+ :rtype: Union[XAAutomatorWorkflow, None]
+
+ .. versionadded:: 0.0.4
+ """
+ returnself.by_property("result",result)
+
+
[docs]defby_name(self,name:str)->Union['XAAutomatorWorkflow',None]:
+ """Retrieves the first workflow whose name matches the given name, if one exists.
+
+ :return: The desired workflow, if it is found
+ :rtype: Union[XAAutomatorWorkflow, None]
+
+ .. versionadded:: 0.0.4
+ """
+ returnself.by_property("name",name)
[docs]classXAAutomatorWorkflow(XAAutomatorDocument):
+ """A class for managing and interacting with Automator workflows.
+
+ .. seealso:: :class:`XAAutomatorApplication`
+
+ .. versionadded:: 0.0.4
+ """
+ def__init__(self,properties):
+ super().__init__(properties)
+ self.current_action:XAAutomatorAction#: The current or most recent action of the workflow
+ self.execution_error_message:str#: The text error message generated by the most recent execution
+ self.execution_error_number:int#: The numeric error code generated by the most recent execution
+ self.execution_id:str#: The unique identifier for the current or most recent execution
+ self.execution_result:Any#: The result of the most resent execution
+ self.name:str#: The name of the workflow
+
+ @property
+ defcurrent_action(self)->XAAutomatorAction:
+ returnself._new_element(self.xa_elem.currentAction(),XAAutomatorAction)
+
+ @property
+ defexecution_error_message(self)->str:
+ returnself.xa_elem.executionErrorMessage()
+
+ @property
+ defexecution_error_number(self)->int:
+ returnself.xa_elem.executionErrorNumber()
+
+ @property
+ defexecution_id(self)->str:
+ returnself.xa_elem.executionId()
+
+ @property
+ defexecution_result(self)->Any:
+ returnself.xa_elem.executionResult().get()
+
+ @property
+ defname(self)->str:
+ returnself.xa_elem.name()
+
+
[docs]defexecute(self)->Any:
+ """Executes the workflow.
+
+ :return: The return value of the workflow after execution
+ :rtype: Any
+
+ .. versionadded:: 0.0.5
+ """
+ returnself.xa_elem.execute()
+
+
[docs]defautomator_actions(self,filter:Union[dict,None]=None)->'XAAutomatorActionList':
+ """Returns a list of actions, as PyXA objects, matching the given filter.
+
+ :param filter: Keys and values to filter actions by, defaults to None
+ :type filter: dict, optional
+ :return: A PyXA list object wrapping a list of actions
+ :rtype: XAAutomatorActionList
+
+ .. versionadded:: 0.0.4
+ """
+ returnself._new_element(self.xa_elem.AutomatorActions(),XAAutomatorActionList,filter)
+
+
[docs]defvariables(self,filter:Union[dict,None]=None)->'XAAutomatorVariableList':
+ """Returns a list of variables, as PyXA objects, matching the given filter.
+
+ :param filter: Keys and values to filter variables by, defaults to None
+ :type filter: dict, optional
+ :return: A PyXA list object wrapping a list of variables
+ :rtype: XAAutomatorVariableList
+
+ .. versionadded:: 0.0.4
+ """
+ returnself._new_element(self.xa_elem.variables(),XAAutomatorVariableList,filter)
[docs]defsave(self)->'XAAutomatorWorkflow':
+ """Saves the workflow to the disk at the location specified by :attr:`XAAutomatorWorkflow.path`, or in the downloads folder if no path has been specified.
+
+ :return: The workflow object.
+ :rtype: XAAutomatorWorkflow
+
+ .. versionadded:: 0.0.5
+ """
+ self.xa_elem.saveAs_in_("workflow",self.path)
+ returnself
[docs]defopen(self,path:Union[str,AppKit.NSURL])->'XAAutomatorWorkflow':"""Opens the file at the given filepath. :param target: The path to a file or the URL to a website to open.
@@ -128,7 +132,7 @@
[docs]classXAAutomatorWindow(XABaseScriptable.XASBWindow):"""A class for managing and interacting with Automator windows.
@@ -247,7 +254,7 @@
Source code for PyXA.apps.Automator
self.name:str#: The full title of the windowself.id:int#: The unique identifier for the windowself.index:int#: The index of the window in the front-to-back ordering
- self.bounds:Tuple[Tuple[int,int],Tuple[int,int]]#: The bounding rectangle of the window
+ self.bounds:tuple[int,int,int,int]#: The bounding rectangle of the windowself.floating:bool#: Whether the window floatself.modal:bool#: Whether the window is a modal windowself.closeable:bool#: Whether the window has a close button
@@ -281,16 +288,19 @@
[docs]defid(self)->list[int]:"""Retrieves the ID of each document in the list. :return: The list of document IDs.
- :rtype: List[int]
+ :rtype: list[int] .. versionadded:: 0.0.4 """returnlist(self.xa_elem.arrayByApplyingSelector_("id"))
[docs]deftitle(self)->list[str]:"""Retrieves the title of each document in the list. :return: The list of document titles.
- :rtype: List[str]
+ :rtype: list[str] .. versionadded:: 0.0.4 """returnlist(self.xa_elem.arrayByApplyingSelector_("title"))
[docs]defindex(self)->list[int]:"""Retrieves the index of each document in the list. :return: The list of document indexes.
- :rtype: List[int]
+ :rtype: list[int] .. versionadded:: 0.0.4 """
@@ -451,12 +461,14 @@
[docs]defbundle_id(self)->list[str]:"""Retrieves the bundle identifier of each action in the list. :return: The list of bundle identifiers.
- :rtype: List[str]
+ :rtype: list[str] .. versionadded:: 0.0.4 """returnlist(self.xa_elem.arrayByApplyingSelector_("bundleId"))
[docs]defcategory(self)->list[list[str]]:"""Retrieves the category/categories of each action in the list. :return: The list of categories.
- :rtype: List[List[str]]
+ :rtype: list[list[str]] .. versionadded:: 0.0.4 """returnlist(self.xa_elem.arrayByApplyingSelector_("category"))
[docs]defcomment(self)->list[str]:"""Retrieves the comments of each action in the list. :return: The list of comments.
- :rtype: List[str]
+ :rtype: list[str] .. versionadded:: 0.0.4 """returnlist(self.xa_elem.arrayByApplyingSelector_("comment"))
[docs]defenabled(self)->list[bool]:"""Retrieves the enabled status of each action in the list. :return: The list of enabled status booleans.
- :rtype: List[bool]
+ :rtype: list[bool] .. versionadded:: 0.0.4 """returnlist(self.xa_elem.arrayByApplyingSelector_("enabled"))
[docs]defexecution_error_message(self)->list[str]:"""Retrieves the execution error message of each action in the list. :return: The list of error messages.
- :rtype: List[str]
+ :rtype: list[str] .. versionadded:: 0.0.4 """returnlist(self.xa_elem.arrayByApplyingSelector_("executionErrorMessage"))
[docs]defexecution_error_number(self)->list[int]:"""Retrieves the execution error number of each action in the list. :return: The list of error numbers.
- :rtype: List[int]
+ :rtype: list[int] .. versionadded:: 0.0.4 """returnlist(self.xa_elem.arrayByApplyingSelector_("executionErrorNumber"))
[docs]defexecution_result(self)->list[Any]:"""Retrieves the result value of each action in the list. :return: The list of results.
- :rtype: List[Any]
+ :rtype: list[Any] .. versionadded:: 0.0.4 """returnlist(self.xa_elem.arrayByApplyingSelector_("executionResult"))
[docs]deficon_name(self)->list[str]:"""Retrieves the icon name of each action in the list. :return: The list of icon names.
- :rtype: List[str]
+ :rtype: list[str] .. versionadded:: 0.0.4 """returnlist(self.xa_elem.arrayByApplyingSelector_("iconName"))
[docs]defignores_input(self)->list[bool]:"""Retrieves the ignore input status of each action in the list. :return: The list of ignore input status booleans.
- :rtype: List[bool]
+ :rtype: list[bool] .. versionadded:: 0.0.4 """returnlist(self.xa_elem.arrayByApplyingSelector_("ignoresInput"))
[docs]defindex(self)->list[int]:"""Retrieves the index of each action in the list. :return: The list of action indices.
- :rtype: List[int]
+ :rtype: list[int] .. versionadded:: 0.0.4 """returnlist(self.xa_elem.arrayByApplyingSelector_("index"))
[docs]definput_types(self)->list[list[str]]:"""Retrieves the input types of each action in the list. :return: The list of input types.
- :rtype: List[List[str]]
+ :rtype: list[list[str]] .. versionadded:: 0.0.4 """returnlist(self.xa_elem.arrayByApplyingSelector_("inputTypes"))
[docs]defkeywords(self)->list[list[str]]:"""Retrieves the keywords of each action in the list. :return: The list of keywords.
- :rtype: List[List[str]]
+ :rtype: list[list[str]] .. versionadded:: 0.0.4 """returnlist(self.xa_elem.arrayByApplyingSelector_("keywords"))
[docs]defname(self)->list[str]:"""Retrieves the name of each action in the list. :return: The list of names.
- :rtype: List[str]
+ :rtype: list[str] .. versionadded:: 0.0.4 """returnlist(self.xa_elem.arrayByApplyingSelector_("name"))
[docs]defoutput_types(self)->list[list[str]]:"""Retrieves the output types of each action in the list. :return: The list of output types.
- :rtype: List[List[str]]
+ :rtype: list[list[str]] .. versionadded:: 0.0.4 """
@@ -625,72 +637,72 @@
[docs]defpath(self)->list[str]:"""Retrieves the file path of each action in the list. :return: The list of paths.
- :rtype: List[str]
+ :rtype: list[str] .. versionadded:: 0.0.4 """returnlist(self.xa_elem.arrayByApplyingSelector_("path"))
[docs]defshow_action_when_run(self)->list[bool]:"""Retrieves the status of the show action when run setting of each action in the list. :return: The list of boolean statuses.
- :rtype: List[bool]
+ :rtype: list[bool] .. versionadded:: 0.0.4 """returnlist(self.xa_elem.arrayByApplyingSelector_("showActionWhenRun"))
[docs]deftarget_application(self)->list[list[str]]:"""Retrieves the target application name of each action in the list. :return: The list of target application names.
- :rtype: List[List[str]]
+ :rtype: list[list[str]] .. versionadded:: 0.0.4 """returnlist(self.xa_elem.arrayByApplyingSelector_("targetApplication"))
[docs]defversion(self)->list[str]:"""Retrieves the version of each action in the list. :return: The list of versions.
- :rtype: List[str]
+ :rtype: list[str] .. versionadded:: 0.0.4 """returnlist(self.xa_elem.arrayByApplyingSelector_("version"))
[docs]defwarning_action(self)->list[str]:"""Retrieves the warning action of each action in the list. :return: The list of warning actions.
- :rtype: List[str]
+ :rtype: list[str] .. versionadded:: 0.0.4 """returnlist(self.xa_elem.arrayByApplyingSelector_("warningAction"))
[docs]defwarning_level(self)->list[XAAutomatorApplication.WarningLevel]:"""Retrieves the warning level of each action in the list. :return: The list of warning levels.
- :rtype: List[XAAutomatorApplication.WarningLevel]
+ :rtype: list[XAAutomatorApplication.WarningLevel] .. versionadded:: 0.0.4 """ls=self.xa_elem.arrayByApplyingSelector_("warningLevel")return[XAAutomatorApplication.WarningLevel(x)forxinls]
[docs]defwarning_message(self)->list[str]:"""Retrieves the warning message of each action in the list. :return: The list of warning messages.
- :rtype: List[str]
+ :rtype: list[str] .. versionadded:: 0.0.4 """
@@ -706,7 +718,7 @@
[docs]defby_category(self,category:list[str])->Union['XAAutomatorAction',None]:"""Retrieves the first action whose category matches the given category, if one exists. :return: The desired action, if it is found
@@ -796,7 +808,7 @@
[docs]defby_input_types(self,input_types:list[str])->Union['XAAutomatorAction',None]:"""Retrieves the first action whose input types match the given input types, if one exists. :return: The desired action, if it is found
@@ -806,7 +818,7 @@
[docs]defby_keywords(self,keywords:list[str])->Union['XAAutomatorAction',None]:"""Retrieves the first action whose keywords match the given keywords, if one exists. :return: The desired action, if it is found
@@ -826,7 +838,7 @@
[docs]defby_output_types(self,output_types:list[str])->Union['XAAutomatorAction',None]:"""Retrieves the first action whose output types match the given output types, if one exists. :return: The desired action, if it is found
@@ -866,7 +878,7 @@
[docs]defby_target_application(self,target_application:list[str])->Union['XAAutomatorAction',None]:"""Retrieves the first action whose target application matches the given application name, if one exists. :return: The desired action, if it is found
@@ -929,7 +941,7 @@
Source code for PyXA.apps.Automator
def__init__(self,properties):super().__init__(properties)self.bundle_id:str#: The bundle identifier for the action
- self.category:List[str]#: The category that contains the action
+ self.category:list[str]#: The category that contains the actionself.comment:str#: The comment for the name of the actionself.enabled:bool#: Whether the action is enabledself.execution_error_message:str#: The text error message generated by execution of the action
@@ -939,14 +951,14 @@
Source code for PyXA.apps.Automator
self.id:str#: The unique identifier for the actionself.ignores_input:bool#: Whether the action ignores input when runself.index:int#: The index of the action from the first action in the workflow
- self.input_types:List[str]#: The input types accepted by the action
- self.keywords:List[str]#: The keywords that describe the action
+ self.input_types:list[str]#: The input types accepted by the action
+ self.keywords:list[str]#: The keywords that describe the actionself.name:str#: The localized name of the action
- self.output_types:List[str]#: The output types produces by the action
+ self.output_types:list[str]#: The output types produces by the actionself.parent_workflow:XAAutomatorWorkflow#: The workflow that contains the actionself.path:str#: The path of the file that contains the actionself.show_action_when_run:bool#: Whether the action should show its user interface when run
- self.target_application:List[str]#: The application(s) with which the action communicates
+ self.target_application:list[str]#: The application(s) with which the action communicatesself.version:str#: The version of the actionself.warning_action:str#: The action suggested by the warning, if anyself.warning_level:XAAutomatorApplication.WarningLevel#: The level of the warning, increasing in likelihood of data loss
@@ -957,7 +969,7 @@
[docs]defkind(self)->list[str]:"""Retrieves the resource type of each resource in the list. :return: The list of resource types.
- :rtype: List[str]
+ :rtype: list[str] .. versionadded:: 0.0.4 """returnlist(self.xa_elem.arrayByApplyingSelector_("kind"))
[docs]defname(self)->list[str]:"""Retrieves the name of each resource in the list. :return: The list of resource names.
- :rtype: List[str]
+ :rtype: list[str] .. versionadded:: 0.0.4 """returnlist(self.xa_elem.arrayByApplyingSelector_("name"))
[docs]defresource(self)->list[str]:"""Retrieves the specification of each resource in the list. :return: The list of resource specifications.
- :rtype: List[str]
+ :rtype: list[str] .. versionadded:: 0.0.4 """returnlist(self.xa_elem.arrayByApplyingSelector_("resource"))
[docs]defversion(self)->list[int]:"""Retrieves the version of each resource in the list. :return: The list of resource versions.
- :rtype: List[int]
+ :rtype: list[int] .. versionadded:: 0.0.4 """
@@ -1233,31 +1245,31 @@
[docs]defdefault_value(self)->list[Any]:"""Retrieves the default value of each setting in the list. :return: The list of default values.
- :rtype: List[Any]
+ :rtype: list[Any] .. versionadded:: 0.0.4 """returnlist(self.xa_elem.arrayByApplyingSelector_("defaultValue"))
[docs]defname(self)->list[str]:"""Retrieves the name of each setting in the list. :return: The list of setting names.
- :rtype: List[str]
+ :rtype: list[str] .. versionadded:: 0.0.4 """returnlist(self.xa_elem.arrayByApplyingSelector_("name"))
[docs]defvalue(self)->list[Any]:"""Retrieves the current value of each setting in the list. :return: The list of current values.
- :rtype: List[Any]
+ :rtype: list[Any] .. versionadded:: 0.0.4 """
@@ -1345,31 +1357,31 @@
[docs]defname(self)->list[str]:"""Retrieves the name of each variable in the list. :return: The list of variable names.
- :rtype: List[Any]
+ :rtype: list[Any] .. versionadded:: 0.0.4 """returnlist(self.xa_elem.arrayByApplyingSelector_("name"))
[docs]defsettable(self)->list[bool]:"""Retrieves the value of the settable attribute of each variable in the list. :return: The list of settable status booleans.
- :rtype: List[bool]
+ :rtype: list[bool] .. versionadded:: 0.0.4 """returnlist(self.xa_elem.arrayByApplyingSelector_("settable"))
[docs]defvalue(self)->list[Any]:"""Retrieves the current value of each variable in the list. :return: The list of current values.
- :rtype: List[Any]
+ :rtype: list[Any] .. versionadded:: 0.0.4 """
@@ -1470,51 +1482,51 @@
[docs]defexecution_error_message(self)->list[str]:"""Retrieves the execution error message of each workflow in the list. :return: The list of error messages.
- :rtype: List[str]
+ :rtype: list[str] .. versionadded:: 0.0.4 """returnlist(self.xa_elem.arrayByApplyingSelector_("executionErrorMessage"))
[docs]defexecution_error_number(self)->list[int]:"""Retrieves the execution error numbers of each workflow in the list. :return: The list of error numbers.
- :rtype: List[int]
+ :rtype: list[int] .. versionadded:: 0.0.4 """returnlist(self.xa_elem.arrayByApplyingSelector_("executionErrorNumber"))
[docs]defexecution_id(self)->list[str]:"""Retrieves the execution ID of each workflow in the list. :return: The list of execution IDs.
- :rtype: List[str]
+ :rtype: list[str] .. versionadded:: 0.0.4 """returnlist(self.xa_elem.arrayByApplyingSelector_("executionId"))
[docs]defexecution_result(self)->list[Any]:"""Retrieves the execution result of each workflow in the list. :return: The list of results.
- :rtype: List[Any]
+ :rtype: list[Any] .. versionadded:: 0.0.4 """returnlist(self.xa_elem.arrayByApplyingSelector_("executionResult"))
[docs]defname(self)->list[str]:"""Retrieves the name of each workflow in the list. :return: The list of workflow names.
- :rtype: List[str]
+ :rtype: list[str] .. versionadded:: 0.0.4 """
@@ -1623,10 +1635,6 @@
[docs]classXABikeApplication(XABaseScriptable.XASBApplication,XACanOpenPath):
+ """A class for managing and interacting with Bike.app.
+
+ .. versionadded:: 0.1.0
+ """
+
+
+ def__init__(self,properties):
+ super().__init__(properties)
+ self.xa_wcls=XABikeWindow
+
+ self.name:str#: The name of the application
+ self.frontmost:bool#: Whether Bike is the frontmost application
+ self.version:str#: The version of Bike.app
+ self.font_size:Union[int,float]#: Bike font size preference
+ self.background_color:XABase.XAColor#: Bike background color preference
+ self.foreground_color:XABase.XAColor#: Bike foreground color preference
+
+ @property
+ defname(self)->str:
+ returnself.xa_scel.name()
+
+ @property
+ deffrontmost(self)->bool:
+ returnself.xa_scel.frontmost()
+
+ @property
+ defversion(self)->str:
+ returnself.xa_scel.version()
+
+ @property
+ deffont_size(self)->Union[int,float]:
+ returnself.xa_scel.fontSize()
+
+ @font_size.setter
+ deffont_size(self,font_size:Union[int,float]):
+ self.set_property('fontSize',font_size)
+
+ @property
+ defbackground_color(self)->XABase.XAColor:
+ returnXABase.XAColor(self.xa_scel.backgroundColor())
+
+ @background_color.setter
+ defbackground_color(self,background_color:XABase.XAColor):
+ self.set_property('backgroundColor',background_color.xa_elem)
+
+ @property
+ defforeground_color(self)->XABase.XAColor:
+ returnXABase.XAColor(self.xa_scel.foregroundColor())
+
+ @foreground_color.setter
+ defforeground_color(self,foreground_color:XABase.XAColor):
+ self.set_property('foregroundColor',foreground_color.xa_elem)
+
+
[docs]defdocuments(self,filter:dict=None)->Union['XABikeDocumentList',None]:
+ """Returns a list of documents, as PyXA-wrapped objects, matching the given filter.
+
+ :param filter: A dictionary specifying property-value pairs that all returned documents will have, or None
+ :type filter: Union[dict, None]
+ :return: The list of documents
+ :rtype: XABikeDocumentList
+
+ :Example:
+
+ >>> import PyXA
+ >>> app = PyXA.application("Bike")
+ >>> print(app.documents())
+ <<class 'PyXA.apps.Bike.XABikeDocumentList'>['Untitled', 'PyXA Notes.bike']>
+
+ .. versionadded:: 0.1.0
+ """
+ returnself._new_element(self.xa_scel.documents(),XABikeDocumentList,filter)
+
+
[docs]defmake(self,specifier:str,properties:Union[dict,None]=None)->XABase.XAObject:
+ """Creates a new element of the given specifier class without adding it to any list.
+
+ Use :func:`XABase.XAList.push` to push the element onto a list.
+
+ :param specifier: The classname of the object to create
+ :type specifier: str
+ :param properties: The properties to give the object
+ :type properties: dict
+ :return: A PyXA wrapped form of the object
+ :rtype: XABase.XAObject
+
+ :Example 1: Add new rows to the current document
+
+ >>> import PyXA
+ >>> app = PyXA.application("Bike")
+ >>> front_doc_rows = app.front_window.document.rows()
+ >>>
+ >>> row1 = app.make("row", {"name": "This is a new row!"})
+ >>> row2 = app.make("row", {"name": "This is another new row!"})
+ >>> row3 = app.make("row", {"name": "This is a third new row!"})
+ >>>
+ >>> front_doc_rows.push(row1) # Add to the end of the document
+ >>> front_doc_rows.insert(row2, 0) # Insert at the beginning of the document
+ >>> front_doc_rows.insert(row3, 5) # Insert at the middle of the document
+
+ .. versionadded:: 0.1,0
+ """
+ ifpropertiesisNone:
+ properties={}
+
+ obj=self.xa_scel.classForScriptingClass_(specifier).alloc().initWithProperties_(properties)
+
+ ifspecifier=="window":
+ raiseUnconstructableClassError("Windows cannot be created for Bike.app.")
+ elifspecifier=="document":
+ returnself._new_element(obj,XABikeDocument)
+ elifspecifier=="row":
+ returnself._new_element(obj,XABikeRow)
+ elifspecifier=="attribute":
+ returnself._new_element(obj,XABikeAttribute)
+
+
+
+
+
[docs]classXABikeWindow(XABaseScriptable.XASBWindow):
+ """A window of Bike.app.
+
+ .. versionadded:: 0.1.0
+ """
+
+ def__init__(self,properties):
+ super().__init__(properties)
+
+ self.name:str#: The title of the window
+ self.id:int#: The unique identifier of the window
+ self.index:int#: The index of the window, ordered front to back
+ self.bounds:Tuple[int,int,int,int]#: The bounding rectangle of the window
+ self.closeable:bool#: Whether the window has a close button
+ self.miniaturizable:bool#: Whether the window has a minimize button
+ self.miniaturized:bool#: Whether the window is currently minimized
+ self.resizable:bool#: Whether the window can be resized
+ self.visible:bool#: Whether the window is currently visible
+ self.zoomable:bool#: Whether the window has a zoom button
+ self.zoomed:bool#: Whether the window is currently zoomed
+ self.document:XABikeDocument#: The document whose contents are currently displayed in the window
+
+ @property
+ defname(self)->str:
+ returnself.xa_elem.name()
+
+ @property
+ defid(self)->int:
+ returnself.xa_elem.id()
+
+ @property
+ defindex(self)->int:
+ returnself.xa_elem.index()
+
+ @index.setter
+ defindex(self,index:int):
+ self.set_property('index',index)
+
+ @property
+ defbounds(self)->Tuple[int,int,int,int]:
+ rect=self.xa_elem.bounds()
+ origin=rect.origin
+ size=rect.size
+ return(origin.x,origin.y,size.width,size.height)
+
+ @bounds.setter
+ defbounds(self,bounds:Tuple[int,int,int,int]):
+ x=bounds[0]
+ y=bounds[1]
+ w=bounds[2]
+ h=bounds[3]
+ value=AppKit.NSValue.valueWithRect_(AppKit.NSMakeRect(x,y,w,h))
+ self.set_property("bounds",value)
+
+ @property
+ defcloseable(self)->bool:
+ returnself.xa_elem.closeable()
+
+ @property
+ defminiaturizable(self)->bool:
+ returnself.xa_elem.miniaturizable()
+
+ @property
+ defminiaturized(self)->bool:
+ returnself.xa_elem.miniaturized()
+
+ @miniaturized.setter
+ defminiaturized(self,miniaturized:bool):
+ self.set_property('miniaturized',miniaturized)
+
+ @property
+ defresizable(self)->bool:
+ returnself.xa_elem.resizable()
+
+ @property
+ defvisible(self)->bool:
+ returnself.xa_elem.visible()
+
+ @visible.setter
+ defvisible(self,visible:bool):
+ self.set_property('visible',visible)
+
+ @property
+ defzoomable(self)->bool:
+ returnself.xa_elem.zoomable()
+
+ @property
+ defzoomed(self)->bool:
+ returnself.xa_elem.zoomed()
+
+ @zoomed.setter
+ defzoomed(self,zoomed:bool):
+ self.set_property('zoomed',zoomed)
+
+ @property
+ defdocument(self)->'XABikeDocument':
+ returnself._new_element(self.xa_elem.document(),XABikeDocument)
+
+ def__repr__(self):
+ return"<"+str(type(self))+str(self.name())+">"
+
+
+
+
+
[docs]classXABikeDocumentList(XABase.XAList,XACanOpenPath,XAClipboardCodable):
+ """A wrapper around lists of Bike 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.
+
+ .. versionadded:: 0.1.0
+ """
+ def__init__(self,properties:dict,filter:Union[dict,None]=None):
+ super().__init__(properties,XABikeDocument,filter)
+
+
[docs]defname(self)->List[str]:
+ """Gets the name of each document in the list.
+
+ :return: A list of document names
+ :rtype: List[str]
+
+ .. versionadded:: 0.1.0
+ """
+ returnlist(self.xa_elem.arrayByApplyingSelector_("name"))
+
+
[docs]defmodified(self)->List[bool]:
+ """Gets the modified status of each document in the list.
+
+ :return: A list of document modified status booleans
+ :rtype: List[bool]
+
+ .. versionadded:: 0.1.0
+ """
+ returnlist(self.xa_elem.arrayByApplyingSelector_("modified"))
+
+
[docs]deffile(self)->List[XABase.XAPath]:
+ """Gets the file path of each document in the list.
+
+ :return: A list of document file paths
+ :rtype: List[XABase.XAPath]
+
+ .. versionadded:: 0.1.0
+ """
+ ls=self.xa_elem.arrayByApplyingSelector_("file")
+ return[XABase.XAPath(x)forxinls]
+
+
[docs]defid(self)->List[str]:
+ """Gets the ID of each document in the list.
+
+ :return: A list of document IDs
+ :rtype: List[str]
+
+ .. versionadded:: 0.1.0
+ """
+ returnlist(self.xa_elem.arrayByApplyingSelector_("id"))
+
+
[docs]defurl(self)->List[XABase.XAURL]:
+ """Gets the URL of each document in the list.
+
+ :return: A list of document urls
+ :rtype: List[XABase.XAURL]
+
+ .. versionadded:: 0.1.0
+ """
+ ls=self.xa_elem.arrayByApplyingSelector_("url")
+ return[XABase.XAURL(x)forxinls]
+
+
[docs]defroot_row(self)->'XABikeRowList':
+ """Gets the root row of each document in the list.
+
+ :return: A list of document root rows
+ :rtype: XABikeRowList
+
+ .. versionadded:: 0.1.0
+ """
+ ls=self.xa_elem.arrayByApplyingSelector_("rootRow")
+ returnself._new_element(ls,XABikeRowList)
+
+
[docs]defentireContents(self)->'XABikeRowList':
+ """Gets the entire contents of each document in the list.
+
+ :return: A list of document rows
+ :rtype: XABikeRowLists
+
+ .. versionadded:: 0.1.0
+ """
+ ls=self.xa_elem.arrayByApplyingSelector_("entireContents")
+ ls=[rowforcontentsinlsforrowincontents]
+ returnself._new_element(ls,XABikeRowList)
+
+
[docs]deffocused_row(self)->'XABikeRowList':
+ """Gets the focused row of each document in the list.
+
+ :return: A list of document focused rows
+ :rtype: XABikeRowList
+
+ .. versionadded:: 0.1.0
+ """
+ ls=self.xa_elem.arrayByApplyingSelector_("focusedRow")
+ returnself._new_element(ls,XABikeRowList)
+
+
[docs]defhoisted_row(self)->'XABikeRowList':
+ """Gets the hoisted row of each document in the list.
+
+ :return: A list of document hoisted rows
+ :rtype: XABikeRowList
+
+ .. versionadded:: 0.1.0
+ """
+ ls=self.xa_elem.arrayByApplyingSelector_("hoistedRow")
+ returnself._new_element(ls,XABikeRowList)
+
+
[docs]defselected_text(self)->List[str]:
+ """Gets the selected text of each document in the list.
+
+ :return: A list of document selected texts
+ :rtype: List[str]
+
+ .. versionadded:: 0.1.0
+ """
+ returnlist(self.xa_elem.arrayByApplyingSelector_("selectedText"))
+
+
[docs]defselection_row(self)->'XABikeRowList':
+ """Gets the selection row of each document in the list.
+
+ :return: A list of document selection rows
+ :rtype: XABikeRowList
+
+ .. versionadded:: 0.1.0
+ """
+ ls=self.xa_elem.arrayByApplyingSelector_("selectionRow")
+ returnself._new_element(ls,XABikeRowList)
+
+
[docs]defselection_rows(self)->'XABikeRowList':
+ """Gets the selection rows of each document in the list.
+
+ :return: A list of document selection rows
+ :rtype: XABikeRowList
+
+ .. versionadded:: 0.1.0
+ """
+ ls=self.xa_elem.arrayByApplyingSelector_("selectionRows")
+ ls=[rowforcontentsinlsforrowincontents]
+ returnself._new_element(ls,XABikeRowList)
+
+
[docs]defby_name(self,name:str)->Union['XABikeDocument',None]:
+ """Retrieves the document whose name matches the given name, if one exists.
+
+ :return: The desired document, if it is found
+ :rtype: Union[XABikeDocument, None]
+
+ .. versionadded:: 0.1.0
+ """
+ returnself.by_property("name",name)
+
+
[docs]defby_modified(self,modified:bool)->Union['XABikeDocument',None]:
+ """Retrieves the first document whose modified status matches the given boolean value, if one exists.
+
+ :return: The desired document, if it is found
+ :rtype: Union[XABikeDocument, None]
+
+ .. versionadded:: 0.1.0
+ """
+ returnself.by_property("modified",modified)
+
+
[docs]defby_file(self,file:Union[str,XABase.XAPath])->Union['XABikeDocument',None]:
+ """Retrieves the document whose file path matches the given path, if one exists.
+
+ :return: The desired document, if it is found
+ :rtype: Union[XABikeDocument, None]
+
+ .. versionadded:: 0.1.0
+ """
+ ifisinstance(file,XABase.XAPath):
+ file=file.path
+ returnself.by_property("file",file)
+
+
[docs]defby_id(self,id:str)->Union['XABikeDocument',None]:
+ """Retrieves the document whose ID matches the given ID, if one exists.
+
+ :return: The desired document, if it is found
+ :rtype: Union[XABikeDocument, None]
+
+ .. versionadded:: 0.1.0
+ """
+ returnself.by_property("id",id)
+
+
[docs]defby_url(self,url:Union[str,XABase.XAURL])->Union['XABikeDocument',None]:
+ """Retrieves the document whose URL matches the given URL, if one exists.
+
+ :return: The desired document, if it is found
+ :rtype: Union[XABikeDocument, None]
+
+ .. versionadded:: 0.1.0
+ """
+ ifisinstance(url,XABase.XAURL):
+ url=url.url
+ returnself.by_property("url",url)
+
+
[docs]defby_root_row(self,root_row:'XABikeRow')->Union['XABikeDocument',None]:
+ """Retrieves the document whose root row matches the given row, if one exists.
+
+ :return: The desired document, if it is found
+ :rtype: Union[XABikeDocument, None]
+
+ .. versionadded:: 0.1.0
+ """
+ returnself.by_property("rootRow",root_row.xa_elem)
+
+
[docs]defby_entire_contents(self,entire_contents:Union['XABikeRowList',List['XABikeRow']])->Union['XABikeDocument',None]:
+ """Retrieves the document whose entire contents matches the given list of rows, if one exists.
+
+ :return: The desired document, if it is found
+ :rtype: Union[XABikeDocument, None]
+
+ .. versionadded:: 0.1.0
+ """
+ ifisinstance(entire_contents,list):
+ entire_contents=[x.xa_elemforxinentire_contents]
+ returnself.by_property("entireContents",entire_contents)
+ else:
+ returnself.by_property("entireContents",entire_contents.xa_elem)
+
+
[docs]defby_focused_row(self,focused_row:'XABikeRow')->Union['XABikeDocument',None]:
+ """Retrieves the document whose focused row matches the given row, if one exists.
+
+ :return: The desired document, if it is found
+ :rtype: Union[XABikeDocument, None]
+
+ .. versionadded:: 0.1.0
+ """
+ returnself.by_property("focusedRow",focused_row.xa_elem)
+
+
[docs]defby_hoisted_row(self,hoisted_row:'XABikeRow')->Union['XABikeDocument',None]:
+ """Retrieves the document whose hoisted row matches the given row, if one exists.
+
+ :return: The desired document, if it is found
+ :rtype: Union[XABikeDocument, None]
+
+ .. versionadded:: 0.1.0
+ """
+ returnself.by_property("hoistedRow",hoisted_row.xa_elem)
+
+
[docs]defby_selected_text(self,selected_text:str)->Union['XABikeDocument',None]:
+ """Retrieves the document whose selected text matches the given text, if one exists.
+
+ :return: The desired document, if it is found
+ :rtype: Union[XABikeDocument, None]
+
+ .. versionadded:: 0.1.0
+ """
+ returnself.by_property("selectedText",selected_text)
+
+
[docs]defby_selection_row(self,selection_row:'XABikeRow')->Union['XABikeDocument',None]:
+ """Retrieves the document whose selection row matches the given row, if one exists.
+
+ :return: The desired document, if it is found
+ :rtype: Union[XABikeDocument, None]
+
+ .. versionadded:: 0.1.0
+ """
+ returnself.by_property("selectionRow",selection_row.xa_elem)
+
+
[docs]defby_selection_rows(self,selection_rows:Union['XABikeRowList',List['XABikeRow']])->Union['XABikeDocument',None]:
+ """Retrieves the document whose selection rows match the given list of rows, if one exists.
+
+ :return: The desired document, if it is found
+ :rtype: Union[XABikeDocument, None]
+
+ .. versionadded:: 0.1.0
+ """
+ ifisinstance(selection_rows,list):
+ selection_rows=[x.xa_elemforxinselection_rows]
+ returnself.by_property("selectionRows",selection_rows)
+ else:
+ returnself.by_property("selectionRows",selection_rows.xa_elem)
+
+
[docs]defclose(self,save:'XACloseable.SaveOption'=None):
+ """Closes every document in the list. Leaves the last document open if it is the only document open in the application.
+
+ :param save: Whether to save the documents before closing, defaults to YES
+ :type save: XACloseable.SaveOption, optional
+
+ .. versionadded:: 0.1.0
+ """
+ ifsaveisNone:
+ save=1852776480
+ else:
+ save=save.value
+
+ fordocumentinself.xa_elem:
+ document.closeSaving_savingIn_(save,None)
[docs]classXABikeDocument(XABase.XAObject,XACloseable):
+ """A document of Bike.app.
+
+ .. versionadded:: 0.1.0
+ """
+
+ def__init__(self,properties):
+ super().__init__(properties)
+
+ self.name:str#: The name of the document
+ self.modified:bool#: Whether the document has been modified since it was last saved
+ self.file:XABase.XAPath#: The location of the document on disk, if it has one
+ self.id:str#: The unique and persistent identifier for the document
+ self.url:XABase.XAURL#: The Bike URL link for the document
+ self.root_row:XABikeRow#: The top 'root' row of the document, not visible in the outline editor
+ self.entire_contents:XABikeRowList#: All rows in the document
+ self.focused_row:XABikeRow#: The currently focused row
+ self.hoisted_row:XABikeRow#: The currently hoisted row
+ self.selected_text:str#: The currently selected text
+ self.selection_row:XABikeRow#: The row intersecting the selected text head
+ self.selection_rows:XABikeRowList#: All rows intersecting the selected text
+
+ @property
+ defname(self)->str:
+ returnself.xa_elem.name()
+
+ @property
+ defmodified(self)->str:
+ returnself.xa_elem.modified()
+
+ @property
+ deffile(self)->XABase.XAPath:
+ returnXABase.XAPath(self.xa_elem.file())
+
+ @property
+ defid(self)->str:
+ returnself.xa_elem.id()
+
+ @property
+ defurl(self)->XABase.XAURL:
+ returnXABase.XAURL(self.xa_elem.url())
+
+ @property
+ defroot_row(self)->'XABikeRow':
+ returnself._new_element(self.xa_elem.rootRow(),XABikeRow)
+
+ @property
+ defentire_contents(self)->'XABikeRowList':
+ returnself._new_element(self.xa_elem.entireContents(),XABikeRowList)
+
+ @property
+ deffocused_row(self)->'XABikeRow':
+ returnself._new_element(self.xa_elem.focusedRow(),XABikeRow)
+
+ @focused_row.setter
+ deffocused_row(self,focused_row:'XABikeRow'):
+ self.set_property('focusedRow',focused_row.xa_elem)
+
+ @property
+ defhoisted_row(self)->'XABikeRow':
+ returnself._new_element(self.xa_elem.hoisted_row(),XABikeRow)
+
+ @hoisted_row.setter
+ defhoisted_row(self,hoisted_row:'XABikeRow'):
+ self.set_property('hoistedRow',hoisted_row.xa_elem)
+
+ @property
+ defselected_text(self)->str:
+ returnself.xa_elem.selectedText()
+
+ @property
+ defselection_row(self)->'XABikeRow':
+ returnself._new_element(self.xa_elem.selectionRow(),XABikeRow)
+
+ @property
+ defselection_rows(self)->'XABikeRowList':
+ returnself._new_element(self.xa_elem.selectionRows(),XABikeRowList)
+
+
[docs]defsave(self,path:Union[str,XABase.XAPath,None]=None,format:XABikeApplication.FileFormat=XABikeApplication.FileFormat.BIKE):
+ """Saves the document to the specified location, or at its existing location.
+
+ :param path: The location to save the document in, defaults to None
+ :type path: Union[str, XABase.XAPath, None], optional
+ :param format: The format to save the document as, defaults to XABikeApplication.FileFormat.BIKE
+ :type format: XABikeApplication.FileFormat, optional
+
+ :Example:
+
+ >>> import PyXA
+ >>> app = PyXA.application("Bike")
+ >>> doc = app.documents()[0]
+ >>> doc.save("/Users/exampleUser/Documents/Notes.opml", app.FileFormat.OPML)
+
+ .. versionadded:: 0.1.0
+ """
+ ifpathisNone:
+ path=self.xa_elem.file()
+ elifisinstance(path,str):
+ path=XABase.XAPath(path).xa_elem
+ self.xa_elem.saveIn_as_(path,format.value)
+
+
[docs]defrows(self,filter:dict=None)->Union['XABikeRowList',None]:
+ """Returns a list of rows, as PyXA-wrapped objects, matching the given filter.
+
+ :param filter: A dictionary specifying property-value pairs that all returned rows will have, or None
+ :type filter: Union[dict, None]
+ :return: The list of rows
+ :rtype: XABikeRowList
+
+ :Example:
+
+ >>> import PyXA
+ >>> app = PyXA.application("Bike")
+ >>> doc = app.front_window.document
+ >>> print(doc.rows())
+ <<class 'PyXA.apps.Bike.XABikeRowList'>['Row 1', 'Row 2', 'Row 2.1']>
+
+ .. versionadded:: 0.1.0
+ """
+ returnself._new_element(self.xa_elem.rows(),XABikeRowList,filter)
[docs]classXABikeRowList(XABase.XAList):
+ """A wrapper around a list of rows.
+
+ All properties of row objects can be accessed via methods on the list, returning a list of each row's value for the property.
+
+ .. versionadded:: 0.1.0
+ """
+ def__init__(self,properties:dict,filter:Union[dict,None]=None):
+ super().__init__(properties,XABikeRow,filter)
+
+
[docs]defid(self)->List[str]:
+ """Gets the ID of each row in the list.
+
+ :return: A list of row IDs
+ :rtype: List[str]
+
+ .. versionadded:: 0.1.0
+ """
+ returnlist(self.xa_elem.arrayByApplyingSelector_("id"))
+
+
[docs]defurl(self)->List[XABase.XAURL]:
+ """Gets the URL of each row in the list.
+
+ :return: A list of row URLs
+ :rtype: List[XABase.XAURL]
+
+ .. versionadded:: 0.1.0
+ """
+ ls=self.xa_elem.arrayByApplyingSelector_("url")
+ return[XABase.XAURL(x)forxinls]
+
+
[docs]deflevel(self)->List[int]:
+ """Gets the level of each row in the list.
+
+ :return: A list of row levels
+ :rtype: List[int]
+
+ .. versionadded:: 0.1.0
+ """
+ returnlist(self.xa_elem.arrayByApplyingSelector_("level"))
+
+
[docs]defcontains_rows(self)->List[bool]:
+ """Gets the contains rows status of each row in the list.
+
+ :return: A list of row contains rows status booleans
+ :rtype: List[bool]
+
+ .. versionadded:: 0.1.0
+ """
+ returnlist(self.xa_elem.arrayByApplyingSelector_("containsRows"))
+
+
[docs]defname(self)->List[str]:
+ """Gets the name of each row in the list.
+
+ :return: A list of row names
+ :rtype: List[str]
+
+ .. versionadded:: 0.1.0
+ """
+ returnlist(self.xa_elem.arrayByApplyingSelector_("name"))
+
+
[docs]defcontainer(self)->List[Union[XABikeDocument,'XABikeRow']]:
+ """Gets the container of each row in the list.
+
+ :return: A list of row containers
+ :rtype: List[Union[XABikeDocument, 'XABikeRow']]
+
+ .. versionadded:: 0.1.0
+ """
+ return[x.containerforxinself]
+
+
[docs]defcontainer_row(self)->'XABikeRowList':
+ """Gets the container row of each row in the list.
+
+ :return: A list of row container rows
+ :rtype: XABikeRowList
+
+ .. versionadded:: 0.1.0
+ """
+ ls=self.xa_elem.arrayByApplyingSelector_("containerRow")
+ returnself._new_element(ls,XABikeRowList)
+
+
[docs]defprev_sibling_row(self)->'XABikeRowList':
+ """Gets the previous sibling row of each row in the list.
+
+ :return: A list of row previous sibling rows
+ :rtype: XABikeRowList
+
+ .. versionadded:: 0.1.0
+ """
+ ls=self.xa_elem.arrayByApplyingSelector_("prevSiblingRow")
+ returnself._new_element(ls,XABikeRowList)
+
+
[docs]defnext_sibling_row(self)->'XABikeRowList':
+ """Gets the next sibling row of each row in the list.
+
+ :return: A list of row next sibling rows
+ :rtype: XABikeRowList
+
+ .. versionadded:: 0.1.0
+ """
+ ls=self.xa_elem.arrayByApplyingSelector_("nextSiblingRow")
+ returnself._new_element(ls,XABikeRowList)
+
+
[docs]defentire_contents(self)->'XABikeRowList':
+ """Gets the all contained rows of each row in the list.
+
+ :return: A list of contained rows
+ :rtype: XABikeRowList
+
+ .. versionadded:: 0.1.0
+ """
+ ls=self.xa_elem.arrayByApplyingSelector_("entireContents")
+ ls=[itemforcontentsinlsforitemincontents]
+ returnself._new_element(ls,XABikeRowList)
+
+
[docs]defvisible(self)->List[bool]:
+ """Gets the visible status of each row in the list.
+
+ :return: A list of row visible status booleans
+ :rtype: List[bool]
+
+ .. versionadded:: 0.1.0
+ """
+ returnlist(self.xa_elem.arrayByApplyingSelector_("visible"))
+
+
[docs]defselected(self)->List[bool]:
+ """Gets the selected status of each row in the list.
+
+ :return: A list of row selected status booleans
+ :rtype: List[bool]
+
+ .. versionadded:: 0.1.0
+ """
+ returnlist(self.xa_elem.arrayByApplyingSelector_("selected"))
+
+
[docs]defexpanded(self)->List[bool]:
+ """Gets the expanded status of each row in the list.
+
+ :return: A list of row expanded status booleans
+ :rtype: List[bool]
+
+ .. versionadded:: 0.1.0
+ """
+ returnlist(self.xa_elem.arrayByApplyingSelector_("expanded"))
+
+
[docs]defcollapsed(self)->List[bool]:
+ """Gets the collapsed status of each row in the list.
+
+ :return: A list of row collapsed status booleans
+ :rtype: List[bool]
+
+ .. versionadded:: 0.1.0
+ """
+ returnlist(self.xa_elem.arrayByApplyingSelector_("collapsed"))
+
+
[docs]defby_id(self,id:str)->Union['XABikeRow',None]:
+ """Retrieves the row whose ID matches the given ID, if one exists.
+
+ :return: The desired row, if it is found
+ :rtype: Union[XABikeRow, None]
+
+ .. versionadded:: 0.1.0
+ """
+ returnself.by_property("id",id)
+
+
[docs]defby_url(self,url:Union[str,XABase.XAURL])->Union['XABikeRow',None]:
+ """Retrieves the row whose URL matches the given URL, if one exists.
+
+ :return: The desired row, if it is found
+ :rtype: Union[XABikeRow, None]
+
+ .. versionadded:: 0.1.0
+ """
+ ifisinstance(url,XABase.XAURL):
+ url=url.url
+ returnself.by_property("url",url)
+
+
[docs]defby_level(self,level:int)->Union['XABikeRow',None]:
+ """Retrieves the first row whose level matches the given level, if one exists.
+
+ :return: The desired row, if it is found
+ :rtype: Union[XABikeRow, None]
+
+ .. versionadded:: 0.1.0
+ """
+ returnself.by_property("level",level)
+
+
[docs]defby_contains_rows(self,contains_rows:bool)->Union['XABikeRow',None]:
+ """Retrieves the first row whose contains rows status matches the given boolean value, if one exists.
+
+ :return: The desired row, if it is found
+ :rtype: Union[XABikeRow, None]
+
+ .. versionadded:: 0.1.0
+ """
+ returnself.by_property("containsRows",contains_rows)
+
+
[docs]defby_name(self,name:str)->Union['XABikeRow',None]:
+ """Retrieves the row whose name matches the given name, if one exists.
+
+ :return: The desired row, if it is found
+ :rtype: Union[XABikeRow, None]
+
+ .. versionadded:: 0.1.0
+ """
+ returnself.by_property("name",name)
+
+
[docs]defby_container(self,container:Union[XABikeDocument,'XABikeRow'])->Union['XABikeRow',None]:
+ """Retrieves the first row whose container matches the given container, if one exists.
+
+ :return: The desired row, if it is found
+ :rtype: Union[XABikeRow, None]
+
+ .. versionadded:: 0.1.0
+ """
+ returnself.by_property("container",container.xa_elem)
+
+
[docs]defby_container_row(self,container_row:'XABikeRow')->Union['XABikeRow',None]:
+ """Retrieves the first row whose container row matches the given row, if one exists.
+
+ :return: The desired row, if it is found
+ :rtype: Union[XABikeRow, None]
+
+ .. versionadded:: 0.1.0
+ """
+ returnself.by_property("containerRow",container_row.xa_elem)
+
+
[docs]defby_prev_sibling_row(self,prev_sibling_row:'XABikeRow')->Union['XABikeRow',None]:
+ """Retrieves the row whose previous sibling row matches the given row, if one exists.
+
+ :return: The desired row, if it is found
+ :rtype: Union[XABikeRow, None]
+
+ .. versionadded:: 0.1.0
+ """
+ returnself.by_property("prevSiblingRow",prev_sibling_row.xa_elem)
+
+
[docs]defby_next_sibling_row(self,next_sibling_row:'XABikeRow')->Union['XABikeRow',None]:
+ """Retrieves the row whose next sibling row matches the given row, if one exists.
+
+ :return: The desired row, if it is found
+ :rtype: Union[XABikeRow, None]
+
+ .. versionadded:: 0.1.0
+ """
+ returnself.by_property("nextSiblingRow",next_sibling_row.xa_elem)
+
+
[docs]defby_container_document(self,container_document:XABikeDocument)->Union['XABikeRow',None]:
+ """Retrieves the first row whose container document matches the given document, if one exists.
+
+ :return: The desired row, if it is found
+ :rtype: Union[XABikeRow, None]
+
+ .. versionadded:: 0.1.0
+ """
+ returnself.by_property("containerDocument",container_document.xa_elem)
+
+
[docs]defby_entire_contents(self,entire_contents:Union['XABikeRowList',List['XABikeRow']])->Union['XABikeRow',None]:
+ """Retrieves the row whose entire contents matches the given list of rows, if one exists.
+
+ :return: The desired row, if it is found
+ :rtype: Union[XABikeRow, None]
+
+ .. versionadded:: 0.1.0
+ """
+ ifisinstance(entire_contents,list):
+ entire_contents=[x.xa_elemforxinentire_contents]
+ returnself.by_property("entireContents",entire_contents)
+ else:
+ returnself.by_property("entireContents",entire_contents.xa_elem)
+
+
[docs]defby_visible(self,visible:bool)->Union['XABikeRow',None]:
+ """Retrieves the first row whose visible status matches the given boolean value, if one exists.
+
+ :return: The desired row, if it is found
+ :rtype: Union[XABikeRow, None]
+
+ .. versionadded:: 0.1.0
+ """
+ returnself.by_property("visible",visible)
+
+
[docs]defby_selected(self,selected:bool)->Union['XABikeRow',None]:
+ """Retrieves the first row whose selected status matches the given boolean value, if one exists.
+
+ :return: The desired row, if it is found
+ :rtype: Union[XABikeRow, None]
+
+ .. versionadded:: 0.1.0
+ """
+ returnself.by_property("selected",selected)
+
+
[docs]defby_expanded(self,expanded:bool)->Union['XABikeRow',None]:
+ """Retrieves the first row whose expanded status matches the given boolean value, if one exists.
+
+ :return: The desired row, if it is found
+ :rtype: Union[XABikeRow, None]
+
+ .. versionadded:: 0.1.0
+ """
+ returnself.by_property("expanded",expanded)
+
+
[docs]defby_collapsed(self,collapsed:bool)->Union['XABikeRow',None]:
+ """Retrieves the first row whose collapsed status matches the given boolean value, if one exists.
+
+ :return: The desired row, if it is found
+ :rtype: Union[XABikeRow, None]
+
+ .. versionadded:: 0.1.0
+ """
+ returnself.by_property("collapsed",collapsed)
+
+
[docs]defcollapse(self,all:bool=False):
+ """Collapses all rows in the list, optionally collapsing all of the children as well.
+
+ :param all: Whether to collapse all child rows, defaults to False
+ :type all: bool, optional
+
+ .. versionadded:: 0.1.0
+ """
+ forrowinself.xa_elem:
+ row.collapse_all_([row],all)
+
+
[docs]defexpand(self,all:bool=False):
+ """Expands all rows in the list, optionally expanding all of the children as well.
+
+ :param all: Whether to expand all child rows, defaults to False
+ :type all: bool, optional
+
+ .. versionadded:: 0.1.0
+ """
+ forrowinself.xa_elem:
+ row.expand_all_(row,all)
[docs]classXABikeRow(XABase.XAObject,XADeletable):
+ """A row in an outline.
+
+ .. versionadded:: 0.1.0
+ """
+ def__init__(self,properties):
+ super().__init__(properties)
+
+ self.id:str#: The unique and persistent identifier for the row
+ self.url:XABase.XAURL#: The Bike URL for the row combining the document ID with the item ID
+ self.level:int#: The indentation level for the row in the outline
+ self.contains_rows:bool#: True if the row contains other rows
+ self.name:str#: The plain text content of the row
+ self.container:Union[XABikeRow,XABikeDocument]#: Container of the row
+ self.container_row:XABikeRow#: The row that directly contains this row
+ self.prev_sibling_row:XABikeRow#: The previous row with the same container row as this row
+ self.next_sibling_row:XABikeRow#: The next row with the same container as this row
+ self.container_document:XABikeDocument#: The document that contains this row
+ self.entire_contents:XABikeRowList#: The list of all rows contained by this row
+ self.visible:bool#: True if this row is visible in the window (may require scrolling)
+ self.selected:bool#: True if this row is selected in the window
+ self.expanded:bool#: True if this row is expanded in the window
+ self.collapsed:bool#: True if this row is collapsed in the window
+
+ @property
+ defid(self)->str:
+ returnself.xa_elem.id()
+
+ @property
+ defurl(self)->XABase.XAURL:
+ returnXABase.XAURL(self.xa_elem.url())
+
+ @property
+ deflevel(self)->int:
+ returnself.xa_elem.level()
+
+ @property
+ defcontains_rows(self)->bool:
+ returnself.xa_elem.containsRows()
+
+ @property
+ defname(self)->str:
+ returnself.xa_elem.name()
+
+ @name.setter
+ defname(self,name:str):
+ self.set_property('name',name)
+
+ @property
+ defcontainer(self)->Union['XABikeRow',XABikeDocument]:
+ container=self.xa_elem.container()
+ ifhasattr(container,"level"):
+ returnself._new_element(container,XABikeRow)
+ else:
+ returnself._new_element(container,XABikeDocument)
+
+ @property
+ defcontainer_row(self)->Union['XABikeRow',None]:
+ row=self.xa_elem.containerRow()
+ ifrowisnotNone:
+ returnself._new_element(row,XABikeRow)
+
+ @property
+ defprev_sibling_row(self)->'XABikeRow':
+ returnself._new_element(self.xa_elem.prevSiblingRow(),XABikeRow)
+
+ @property
+ defnext_sibling_row(self)->type:
+ returnself._new_element(self.xa_elem.nextSiblingRow(),XABikeRow)
+
+ @property
+ defcontainer_document(self)->XABikeDocument:
+ returnself._new_element(self.xa_elem.containerDocument(),XABikeDocument)
+
+ @property
+ defentire_contents(self)->XABikeRowList:
+ returnself._new_element(self.xa_elem.entire_contents(),XABikeRowList)
+
+ @property
+ defvisible(self)->bool:
+ returnself.xa_elem.visible()
+
+ @property
+ defselected(self)->bool:
+ returnself.xa_elem.selected()
+
+ @property
+ defexpanded(self)->bool:
+ returnself.xa_elem.expanded()
+
+ @property
+ defcollapsed(self)->bool:
+ returnself.xa_elem.collapsed()
+
+
[docs]defcollapse(self,all:bool=False):
+ """Collapses the row and optionally all rows it contains.
+
+ :param recursive: Whether to also collapse all rows contained by this row, defaults to False
+ :type recursive: bool, optional
+
+ .. versionadded:: 0.1.0
+ """
+ self.xa_elem.collapseAll_(all)
+
+
[docs]defexpand(self,all:bool=False):
+ """Expanded the row and optionally all rows it contains.
+
+ :param recursive: Whether to also expand all rows contained by this row, defaults to False
+ :type recursive: bool, optional
+
+ .. versionadded:: 0.1.0
+ """
+ self.xa_elem.expandAll_(all)
+
+
[docs]defmove_to(self,location:'XABikeRow'):
+ """Makes the row a child of the specified row.
+
+ :param location: The row to move this row to.
+ :type location: XABikeRow
+
+ :Example:
+
+ >>> import PyXA
+ >>> app = PyXA.application("Bike")
+ >>> doc = app.documents()[0]
+ >>> row1 = doc.rows()[0]
+ >>> row2 = doc.rows()[5]
+ >>> row1.move_to(row2)
+
+ .. versionadded:: 0.1.0
+ """
+ self.xa_elem.moveTo_(location.xa_elem)
+
+ # def duplicate(self, location: Union[XABikeDocument, 'XABikeRow', None] = None, properties: Union[dict, None] = None):
+ # """Duplicates the row either in-place or at a specified location.
+
+ # :param location: The document or row to create a duplicate of this row in, defaults to None (duplicate in-place)
+ # :type location: Union[XABikeDocument, XABikeRow, None], optional
+ # :param properties: Properties to set in the new copy right away, defaults to None (no properties changed)
+ # :type properties: Union[dict, None], options
+ # """
+ # if properties is None:
+ # properties = {}
+
+ # if location is None:
+ # self.xa_elem.duplicateTo_withProperties_(self.xa_elem.containerDocument(), properties)
+ # else:
+ # self.xa_elem.duplicateTo_withProperties_(location.xa_elem, properties)
+
+
[docs]defrows(self,filter:dict=None)->Union['XABikeRowList',None]:
+ """Returns a list of rows, as PyXA-wrapped objects, matching the given filter.
+
+ :param filter: A dictionary specifying property-value pairs that all returned rows will have, or None
+ :type filter: Union[dict, None]
+ :return: The list of rows
+ :rtype: XABikeRowList
+
+ :Example:
+
+ >>> import PyXA
+ >>> app = PyXA.application("Bike")
+ >>> doc = app.front_window.document
+ >>> row = doc.rows()[4]
+ >>> print(row.rows())
+ <<class 'PyXA.apps.Bike.XABikeRowList'>['Watch intro movie', 'Glance through features list', 'https://www.hogbaysoftware.com/bike']>
+
+ .. versionadded:: 0.1.0
+ """
+ returnself._new_element(self.xa_elem.rows(),XABikeRowList,filter)
+
+
[docs]defattributes(self,filter:dict=None)->Union['XABikeAttributeList',None]:
+ """Returns a list of attributes, as PyXA-wrapped objects, matching the given filter.
+
+ :param filter: A dictionary specifying property-value pairs that all returned attributes will have, or None
+ :type filter: Union[dict, None]
+ :return: The list of attributes
+ :rtype: XABikeAttributeList
+
+ .. versionadded:: 0.1.0
+ """
+ returnself._new_element(self.xa_elem.attributes(),XABikeAttributeList,filter)
[docs]classXABikeAttributeList(XABase.XAList):
+ """A wrapper around a list of attributes.
+
+ All properties of attribute objects can be accessed via methods on the list, returning a list of each attribute's value for the property.
+
+ .. versionadded:: 0.1.0
+ """
+ def__init__(self,properties:dict,filter:Union[dict,None]=None):
+ super().__init__(properties,XABikeAttribute,filter)
+
+
[docs]defname(self)->List[str]:
+ """Gets the name of each attribute in the list.
+
+ :return: A list of attribute names
+ :rtype: List[str]
+
+ .. versionadded:: 0.1.0
+ """
+ returnlist(self.xa_elem.arrayByApplyingSelector_("name"))
+
+
[docs]defvalue(self)->List[str]:
+ """Gets the value of each attribute in the list.
+
+ :return: A list of attribute values
+ :rtype: List[str]
+
+ .. versionadded:: 0.1.0
+ """
+ returnlist(self.xa_elem.arrayByApplyingSelector_("value"))
+
+
[docs]defcontainer_row(self)->XABikeRowList:
+ """Gets the container row of each attribute in the list.
+
+ :return: A list of attribute container rows
+ :rtype: List[str]
+
+ .. versionadded:: 0.1.0
+ """
+ ls=self.xa_elem.arrayByApplyingSelector_("containerRow")
+ returnself._new_element(ls,XABikeRowList)
+
+
[docs]defby_name(self,name:str)->Union['XABikeAttribute',None]:
+ """Retrieves the attribute whose name matches the given name, if one exists.
+
+ :return: The desired attribute, if it is found
+ :rtype: Union[XABikeAttribute, None]
+
+ .. versionadded:: 0.1.0
+ """
+ returnself.by_property("name",name)
+
+
[docs]defby_value(self,value:str)->Union['XABikeAttribute',None]:
+ """Retrieves the first attribute whose value matches the given value, if one exists.
+
+ :return: The desired attribute, if it is found
+ :rtype: Union[XABikeAttribute, None]
+
+ .. versionadded:: 0.1.0
+ """
+ returnself.by_property("value",value)
+
+
[docs]defby_container_row(self,container_row:XABikeRow)->Union['XABikeAttribute',None]:
+ """Retrieves the first attribute whose container row matches the given row, if one exists.
+
+ :return: The desired attribute, if it is found
+ :rtype: Union[XABikeAttribute, None]
+
+ .. versionadded:: 0.1.0
+ """
+ returnself.by_property("containerRow",container_row.xa_elem)
[docs]classXABikeApplication(XABaseScriptable.XASBApplication,XACanOpenPath):
+ """A class for managing and interacting with Bike.app.
+
+ .. versionadded:: 0.1.0
+ """
+
+
+ def__init__(self,properties):
+ super().__init__(properties)
+ self.xa_wcls=XABikeWindow
+
+ self.name:str#: The name of the application
+ self.frontmost:bool#: Whether Bike is the frontmost application
+ self.version:str#: The version of Bike.app
+ self.font_size:Union[int,float]#: Bike font size preference
+ self.background_color:XABase.XAColor#: Bike background color preference
+ self.foreground_color:XABase.XAColor#: Bike foreground color preference
+
+ @property
+ defname(self)->str:
+ returnself.xa_scel.name()
+
+ @property
+ deffrontmost(self)->bool:
+ returnself.xa_scel.frontmost()
+
+ @property
+ defversion(self)->str:
+ returnself.xa_scel.version()
+
+ @property
+ deffont_size(self)->Union[int,float]:
+ returnself.xa_scel.fontSize()
+
+ @font_size.setter
+ deffont_size(self,font_size:Union[int,float]):
+ self.set_property('fontSize',font_size)
+
+ @property
+ defbackground_color(self)->XABase.XAColor:
+ returnXABase.XAColor(self.xa_scel.backgroundColor())
+
+ @background_color.setter
+ defbackground_color(self,background_color:XABase.XAColor):
+ self.set_property('backgroundColor',background_color.xa_elem)
+
+ @property
+ defforeground_color(self)->XABase.XAColor:
+ returnXABase.XAColor(self.xa_scel.foregroundColor())
+
+ @foreground_color.setter
+ defforeground_color(self,foreground_color:XABase.XAColor):
+ self.set_property('foregroundColor',foreground_color.xa_elem)
+
+
[docs]defdocuments(self,filter:dict=None)->Union['XABikeDocumentList',None]:
+ """Returns a list of documents, as PyXA-wrapped objects, matching the given filter.
+
+ :param filter: A dictionary specifying property-value pairs that all returned documents will have, or None
+ :type filter: Union[dict, None]
+ :return: The list of documents
+ :rtype: XABikeDocumentList
+
+ :Example:
+
+ >>> import PyXA
+ >>> app = PyXA.Application("Bike")
+ >>> print(app.documents())
+ <<class 'PyXA.apps.Bike.XABikeDocumentList'>['Untitled', 'PyXA Notes.bike']>
+
+ .. versionadded:: 0.1.0
+ """
+ returnself._new_element(self.xa_scel.documents(),XABikeDocumentList,filter)
+
+
[docs]defmake(self,specifier:str,properties:Union[dict,None]=None)->XABase.XAObject:
+ """Creates a new element of the given specifier class without adding it to any list.
+
+ Use :func:`XABase.XAList.push` to push the element onto a list.
+
+ :param specifier: The classname of the object to create
+ :type specifier: str
+ :param properties: The properties to give the object
+ :type properties: dict
+ :return: A PyXA wrapped form of the object
+ :rtype: XABase.XAObject
+
+ :Example 1: Add new rows to the current document
+
+ >>> import PyXA
+ >>> app = PyXA.Application("Bike")
+ >>> front_doc_rows = app.front_window.document.rows()
+ >>>
+ >>> row1 = app.make("row", {"name": "This is a new row!"})
+ >>> row2 = app.make("row", {"name": "This is another new row!"})
+ >>> row3 = app.make("row", {"name": "This is a third new row!"})
+ >>>
+ >>> front_doc_rows.push(row1) # Add to the end of the document
+ >>> front_doc_rows.insert(row2, 0) # Insert at the beginning of the document
+ >>> front_doc_rows.insert(row3, 5) # Insert at the middle of the document
+
+ .. versionadded:: 0.1,0
+ """
+ ifpropertiesisNone:
+ properties={}
+
+ obj=self.xa_scel.classForScriptingClass_(specifier).alloc().initWithProperties_(properties)
+
+ ifspecifier=="window":
+ raiseUnconstructableClassError("Windows cannot be created for Bike.app.")
+ elifspecifier=="document":
+ returnself._new_element(obj,XABikeDocument)
+ elifspecifier=="row":
+ returnself._new_element(obj,XABikeRow)
+ elifspecifier=="attribute":
+ returnself._new_element(obj,XABikeAttribute)
+
+
+
+
+
[docs]classXABikeWindow(XABaseScriptable.XASBWindow):
+ """A window of Bike.app.
+
+ .. versionadded:: 0.1.0
+ """
+
+ def__init__(self,properties):
+ super().__init__(properties)
+
+ self.name:str#: The title of the window
+ self.id:int#: The unique identifier of the window
+ self.index:int#: The index of the window, ordered front to back
+ self.bounds:tuple[int,int,int,int]#: The bounding rectangle of the window
+ self.closeable:bool#: Whether the window has a close button
+ self.miniaturizable:bool#: Whether the window has a minimize button
+ self.miniaturized:bool#: Whether the window is currently minimized
+ self.resizable:bool#: Whether the window can be resized
+ self.visible:bool#: Whether the window is currently visible
+ self.zoomable:bool#: Whether the window has a zoom button
+ self.zoomed:bool#: Whether the window is currently zoomed
+ self.document:XABikeDocument#: The document whose contents are currently displayed in the window
+
+ @property
+ defname(self)->str:
+ returnself.xa_elem.name()
+
+ @property
+ defid(self)->int:
+ returnself.xa_elem.id()
+
+ @property
+ defindex(self)->int:
+ returnself.xa_elem.index()
+
+ @index.setter
+ defindex(self,index:int):
+ self.set_property('index',index)
+
+ @property
+ defbounds(self)->tuple[int,int,int,int]:
+ rect=self.xa_elem.bounds()
+ origin=rect.origin
+ size=rect.size
+ return(origin.x,origin.y,size.width,size.height)
+
+ @bounds.setter
+ defbounds(self,bounds:tuple[int,int,int,int]):
+ x=bounds[0]
+ y=bounds[1]
+ w=bounds[2]
+ h=bounds[3]
+ value=AppKit.NSValue.valueWithRect_(AppKit.NSMakeRect(x,y,w,h))
+ self.set_property("bounds",value)
+
+ @property
+ defcloseable(self)->bool:
+ returnself.xa_elem.closeable()
+
+ @property
+ defminiaturizable(self)->bool:
+ returnself.xa_elem.miniaturizable()
+
+ @property
+ defminiaturized(self)->bool:
+ returnself.xa_elem.miniaturized()
+
+ @miniaturized.setter
+ defminiaturized(self,miniaturized:bool):
+ self.set_property('miniaturized',miniaturized)
+
+ @property
+ defresizable(self)->bool:
+ returnself.xa_elem.resizable()
+
+ @property
+ defvisible(self)->bool:
+ returnself.xa_elem.visible()
+
+ @visible.setter
+ defvisible(self,visible:bool):
+ self.set_property('visible',visible)
+
+ @property
+ defzoomable(self)->bool:
+ returnself.xa_elem.zoomable()
+
+ @property
+ defzoomed(self)->bool:
+ returnself.xa_elem.zoomed()
+
+ @zoomed.setter
+ defzoomed(self,zoomed:bool):
+ self.set_property('zoomed',zoomed)
+
+ @property
+ defdocument(self)->'XABikeDocument':
+ returnself._new_element(self.xa_elem.document(),XABikeDocument)
+
+ def__repr__(self):
+ return"<"+str(type(self))+str(self.name())+">"
+
+
+
+
+
[docs]classXABikeDocumentList(XABase.XAList,XACanOpenPath,XAClipboardCodable):
+ """A wrapper around lists of Bike 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.
+
+ .. versionadded:: 0.1.0
+ """
+ def__init__(self,properties:dict,filter:Union[dict,None]=None):
+ super().__init__(properties,XABikeDocument,filter)
+
+
[docs]defname(self)->list[str]:
+ """Gets the name of each document in the list.
+
+ :return: A list of document names
+ :rtype: list[str]
+
+ .. versionadded:: 0.1.0
+ """
+ returnlist(self.xa_elem.arrayByApplyingSelector_("name"))
+
+
[docs]defmodified(self)->list[bool]:
+ """Gets the modified status of each document in the list.
+
+ :return: A list of document modified status booleans
+ :rtype: list[bool]
+
+ .. versionadded:: 0.1.0
+ """
+ returnlist(self.xa_elem.arrayByApplyingSelector_("modified"))
+
+
[docs]deffile(self)->list[XABase.XAPath]:
+ """Gets the file path of each document in the list.
+
+ :return: A list of document file paths
+ :rtype: list[XABase.XAPath]
+
+ .. versionadded:: 0.1.0
+ """
+ ls=self.xa_elem.arrayByApplyingSelector_("file")
+ return[XABase.XAPath(x)forxinls]
+
+
[docs]defid(self)->list[str]:
+ """Gets the ID of each document in the list.
+
+ :return: A list of document IDs
+ :rtype: list[str]
+
+ .. versionadded:: 0.1.0
+ """
+ returnlist(self.xa_elem.arrayByApplyingSelector_("id"))
+
+
[docs]defurl(self)->list[XABase.XAURL]:
+ """Gets the URL of each document in the list.
+
+ :return: A list of document urls
+ :rtype: list[XABase.XAURL]
+
+ .. versionadded:: 0.1.0
+ """
+ ls=self.xa_elem.arrayByApplyingSelector_("url")
+ return[XABase.XAURL(x)forxinls]
+
+
[docs]defroot_row(self)->'XABikeRowList':
+ """Gets the root row of each document in the list.
+
+ :return: A list of document root rows
+ :rtype: XABikeRowList
+
+ .. versionadded:: 0.1.0
+ """
+ ls=self.xa_elem.arrayByApplyingSelector_("rootRow")
+ returnself._new_element(ls,XABikeRowList)
+
+
[docs]defentireContents(self)->'XABikeRowList':
+ """Gets the entire contents of each document in the list.
+
+ :return: A list of document rows
+ :rtype: XABikeRowLists
+
+ .. versionadded:: 0.1.0
+ """
+ ls=self.xa_elem.arrayByApplyingSelector_("entireContents")
+ ls=[rowforcontentsinlsforrowincontents]
+ returnself._new_element(ls,XABikeRowList)
+
+
[docs]deffocused_row(self)->'XABikeRowList':
+ """Gets the focused row of each document in the list.
+
+ :return: A list of document focused rows
+ :rtype: XABikeRowList
+
+ .. versionadded:: 0.1.0
+ """
+ ls=self.xa_elem.arrayByApplyingSelector_("focusedRow")
+ returnself._new_element(ls,XABikeRowList)
+
+
[docs]defhoisted_row(self)->'XABikeRowList':
+ """Gets the hoisted row of each document in the list.
+
+ :return: A list of document hoisted rows
+ :rtype: XABikeRowList
+
+ .. versionadded:: 0.1.0
+ """
+ ls=self.xa_elem.arrayByApplyingSelector_("hoistedRow")
+ returnself._new_element(ls,XABikeRowList)
+
+
[docs]defselected_text(self)->list[str]:
+ """Gets the selected text of each document in the list.
+
+ :return: A list of document selected texts
+ :rtype: list[str]
+
+ .. versionadded:: 0.1.0
+ """
+ returnlist(self.xa_elem.arrayByApplyingSelector_("selectedText"))
+
+
[docs]defselection_row(self)->'XABikeRowList':
+ """Gets the selection row of each document in the list.
+
+ :return: A list of document selection rows
+ :rtype: XABikeRowList
+
+ .. versionadded:: 0.1.0
+ """
+ ls=self.xa_elem.arrayByApplyingSelector_("selectionRow")
+ returnself._new_element(ls,XABikeRowList)
+
+
[docs]defselection_rows(self)->'XABikeRowList':
+ """Gets the selection rows of each document in the list.
+
+ :return: A list of document selection rows
+ :rtype: XABikeRowList
+
+ .. versionadded:: 0.1.0
+ """
+ ls=self.xa_elem.arrayByApplyingSelector_("selectionRows")
+ ls=[rowforcontentsinlsforrowincontents]
+ returnself._new_element(ls,XABikeRowList)
+
+
[docs]defby_name(self,name:str)->Union['XABikeDocument',None]:
+ """Retrieves the document whose name matches the given name, if one exists.
+
+ :return: The desired document, if it is found
+ :rtype: Union[XABikeDocument, None]
+
+ .. versionadded:: 0.1.0
+ """
+ returnself.by_property("name",name)
+
+
[docs]defby_modified(self,modified:bool)->Union['XABikeDocument',None]:
+ """Retrieves the first document whose modified status matches the given boolean value, if one exists.
+
+ :return: The desired document, if it is found
+ :rtype: Union[XABikeDocument, None]
+
+ .. versionadded:: 0.1.0
+ """
+ returnself.by_property("modified",modified)
+
+
[docs]defby_file(self,file:Union[str,XABase.XAPath])->Union['XABikeDocument',None]:
+ """Retrieves the document whose file path matches the given path, if one exists.
+
+ :return: The desired document, if it is found
+ :rtype: Union[XABikeDocument, None]
+
+ .. versionadded:: 0.1.0
+ """
+ ifisinstance(file,XABase.XAPath):
+ file=file.path
+ returnself.by_property("file",file)
+
+
[docs]defby_id(self,id:str)->Union['XABikeDocument',None]:
+ """Retrieves the document whose ID matches the given ID, if one exists.
+
+ :return: The desired document, if it is found
+ :rtype: Union[XABikeDocument, None]
+
+ .. versionadded:: 0.1.0
+ """
+ returnself.by_property("id",id)
+
+
[docs]defby_url(self,url:Union[str,XABase.XAURL])->Union['XABikeDocument',None]:
+ """Retrieves the document whose URL matches the given URL, if one exists.
+
+ :return: The desired document, if it is found
+ :rtype: Union[XABikeDocument, None]
+
+ .. versionadded:: 0.1.0
+ """
+ ifisinstance(url,XABase.XAURL):
+ url=url.url
+ returnself.by_property("url",url)
+
+
[docs]defby_root_row(self,root_row:'XABikeRow')->Union['XABikeDocument',None]:
+ """Retrieves the document whose root row matches the given row, if one exists.
+
+ :return: The desired document, if it is found
+ :rtype: Union[XABikeDocument, None]
+
+ .. versionadded:: 0.1.0
+ """
+ returnself.by_property("rootRow",root_row.xa_elem)
+
+
[docs]defby_entire_contents(self,entire_contents:Union['XABikeRowList',list['XABikeRow']])->Union['XABikeDocument',None]:
+ """Retrieves the document whose entire contents matches the given list of rows, if one exists.
+
+ :return: The desired document, if it is found
+ :rtype: Union[XABikeDocument, None]
+
+ .. versionadded:: 0.1.0
+ """
+ ifisinstance(entire_contents,list):
+ entire_contents=[x.xa_elemforxinentire_contents]
+ returnself.by_property("entireContents",entire_contents)
+ else:
+ returnself.by_property("entireContents",entire_contents.xa_elem)
+
+
[docs]defby_focused_row(self,focused_row:'XABikeRow')->Union['XABikeDocument',None]:
+ """Retrieves the document whose focused row matches the given row, if one exists.
+
+ :return: The desired document, if it is found
+ :rtype: Union[XABikeDocument, None]
+
+ .. versionadded:: 0.1.0
+ """
+ returnself.by_property("focusedRow",focused_row.xa_elem)
+
+
[docs]defby_hoisted_row(self,hoisted_row:'XABikeRow')->Union['XABikeDocument',None]:
+ """Retrieves the document whose hoisted row matches the given row, if one exists.
+
+ :return: The desired document, if it is found
+ :rtype: Union[XABikeDocument, None]
+
+ .. versionadded:: 0.1.0
+ """
+ returnself.by_property("hoistedRow",hoisted_row.xa_elem)
+
+
[docs]defby_selected_text(self,selected_text:str)->Union['XABikeDocument',None]:
+ """Retrieves the document whose selected text matches the given text, if one exists.
+
+ :return: The desired document, if it is found
+ :rtype: Union[XABikeDocument, None]
+
+ .. versionadded:: 0.1.0
+ """
+ returnself.by_property("selectedText",selected_text)
+
+
[docs]defby_selection_row(self,selection_row:'XABikeRow')->Union['XABikeDocument',None]:
+ """Retrieves the document whose selection row matches the given row, if one exists.
+
+ :return: The desired document, if it is found
+ :rtype: Union[XABikeDocument, None]
+
+ .. versionadded:: 0.1.0
+ """
+ returnself.by_property("selectionRow",selection_row.xa_elem)
+
+
[docs]defby_selection_rows(self,selection_rows:Union['XABikeRowList',list['XABikeRow']])->Union['XABikeDocument',None]:
+ """Retrieves the document whose selection rows match the given list of rows, if one exists.
+
+ :return: The desired document, if it is found
+ :rtype: Union[XABikeDocument, None]
+
+ .. versionadded:: 0.1.0
+ """
+ ifisinstance(selection_rows,list):
+ selection_rows=[x.xa_elemforxinselection_rows]
+ returnself.by_property("selectionRows",selection_rows)
+ else:
+ returnself.by_property("selectionRows",selection_rows.xa_elem)
+
+
[docs]defclose(self,save:'XACloseable.SaveOption'=None):
+ """Closes every document in the list. Leaves the last document open if it is the only document open in the application.
+
+ :param save: Whether to save the documents before closing, defaults to YES
+ :type save: XACloseable.SaveOption, optional
+
+ .. versionadded:: 0.1.0
+ """
+ ifsaveisNone:
+ save=1852776480
+ else:
+ save=save.value
+
+ fordocumentinself.xa_elem:
+ document.closeSaving_savingIn_(save,None)
[docs]classXABikeDocument(XABase.XAObject,XACloseable):
+ """A document of Bike.app.
+
+ .. versionadded:: 0.1.0
+ """
+
+ def__init__(self,properties):
+ super().__init__(properties)
+
+ self.name:str#: The name of the document
+ self.modified:bool#: Whether the document has been modified since it was last saved
+ self.file:XABase.XAPath#: The location of the document on disk, if it has one
+ self.id:str#: The unique and persistent identifier for the document
+ self.url:XABase.XAURL#: The Bike URL link for the document
+ self.root_row:XABikeRow#: The top 'root' row of the document, not visible in the outline editor
+ self.entire_contents:XABikeRowList#: All rows in the document
+ self.focused_row:XABikeRow#: The currently focused row
+ self.hoisted_row:XABikeRow#: The currently hoisted row
+ self.selected_text:str#: The currently selected text
+ self.selection_row:XABikeRow#: The row intersecting the selected text head
+ self.selection_rows:XABikeRowList#: All rows intersecting the selected text
+
+ @property
+ defname(self)->str:
+ returnself.xa_elem.name()
+
+ @property
+ defmodified(self)->str:
+ returnself.xa_elem.modified()
+
+ @property
+ deffile(self)->XABase.XAPath:
+ returnXABase.XAPath(self.xa_elem.file())
+
+ @property
+ defid(self)->str:
+ returnself.xa_elem.id()
+
+ @property
+ defurl(self)->XABase.XAURL:
+ returnXABase.XAURL(self.xa_elem.url())
+
+ @property
+ defroot_row(self)->'XABikeRow':
+ returnself._new_element(self.xa_elem.rootRow(),XABikeRow)
+
+ @property
+ defentire_contents(self)->'XABikeRowList':
+ returnself._new_element(self.xa_elem.entireContents(),XABikeRowList)
+
+ @property
+ deffocused_row(self)->'XABikeRow':
+ returnself._new_element(self.xa_elem.focusedRow(),XABikeRow)
+
+ @focused_row.setter
+ deffocused_row(self,focused_row:'XABikeRow'):
+ self.set_property('focusedRow',focused_row.xa_elem)
+
+ @property
+ defhoisted_row(self)->'XABikeRow':
+ returnself._new_element(self.xa_elem.hoisted_row(),XABikeRow)
+
+ @hoisted_row.setter
+ defhoisted_row(self,hoisted_row:'XABikeRow'):
+ self.set_property('hoistedRow',hoisted_row.xa_elem)
+
+ @property
+ defselected_text(self)->str:
+ returnself.xa_elem.selectedText()
+
+ @property
+ defselection_row(self)->'XABikeRow':
+ returnself._new_element(self.xa_elem.selectionRow(),XABikeRow)
+
+ @property
+ defselection_rows(self)->'XABikeRowList':
+ returnself._new_element(self.xa_elem.selectionRows(),XABikeRowList)
+
+
[docs]defsave(self,path:Union[str,XABase.XAPath,None]=None,format:XABikeApplication.FileFormat=XABikeApplication.FileFormat.BIKE):
+ """Saves the document to the specified location, or at its existing location.
+
+ :param path: The location to save the document in, defaults to None
+ :type path: Union[str, XABase.XAPath, None], optional
+ :param format: The format to save the document as, defaults to XABikeApplication.FileFormat.BIKE
+ :type format: XABikeApplication.FileFormat, optional
+
+ :Example:
+
+ >>> import PyXA
+ >>> app = PyXA.Application("Bike")
+ >>> doc = app.documents()[0]
+ >>> doc.save("/Users/exampleUser/Documents/Notes.opml", app.FileFormat.OPML)
+
+ .. versionadded:: 0.1.0
+ """
+ ifpathisNone:
+ path=self.xa_elem.file()
+ elifisinstance(path,str):
+ path=XABase.XAPath(path).xa_elem
+ self.xa_elem.saveIn_as_(path,format.value)
+
+
[docs]defrows(self,filter:dict=None)->Union['XABikeRowList',None]:
+ """Returns a list of rows, as PyXA-wrapped objects, matching the given filter.
+
+ :param filter: A dictionary specifying property-value pairs that all returned rows will have, or None
+ :type filter: Union[dict, None]
+ :return: The list of rows
+ :rtype: XABikeRowList
+
+ :Example:
+
+ >>> import PyXA
+ >>> app = PyXA.Application("Bike")
+ >>> doc = app.front_window.document
+ >>> print(doc.rows())
+ <<class 'PyXA.apps.Bike.XABikeRowList'>['Row 1', 'Row 2', 'Row 2.1']>
+
+ .. versionadded:: 0.1.0
+ """
+ returnself._new_element(self.xa_elem.rows(),XABikeRowList,filter)
[docs]classXABikeRowList(XABase.XAList):
+ """A wrapper around a list of rows.
+
+ All properties of row objects can be accessed via methods on the list, returning a list of each row's value for the property.
+
+ .. versionadded:: 0.1.0
+ """
+ def__init__(self,properties:dict,filter:Union[dict,None]=None):
+ super().__init__(properties,XABikeRow,filter)
+
+
[docs]defid(self)->list[str]:
+ """Gets the ID of each row in the list.
+
+ :return: A list of row IDs
+ :rtype: list[str]
+
+ .. versionadded:: 0.1.0
+ """
+ returnlist(self.xa_elem.arrayByApplyingSelector_("id"))
+
+
[docs]defurl(self)->list[XABase.XAURL]:
+ """Gets the URL of each row in the list.
+
+ :return: A list of row URLs
+ :rtype: list[XABase.XAURL]
+
+ .. versionadded:: 0.1.0
+ """
+ ls=self.xa_elem.arrayByApplyingSelector_("url")
+ return[XABase.XAURL(x)forxinls]
+
+
[docs]deflevel(self)->list[int]:
+ """Gets the level of each row in the list.
+
+ :return: A list of row levels
+ :rtype: list[int]
+
+ .. versionadded:: 0.1.0
+ """
+ returnlist(self.xa_elem.arrayByApplyingSelector_("level"))
+
+
[docs]defcontains_rows(self)->list[bool]:
+ """Gets the contains rows status of each row in the list.
+
+ :return: A list of row contains rows status booleans
+ :rtype: list[bool]
+
+ .. versionadded:: 0.1.0
+ """
+ returnlist(self.xa_elem.arrayByApplyingSelector_("containsRows"))
+
+
[docs]defname(self)->list[str]:
+ """Gets the name of each row in the list.
+
+ :return: A list of row names
+ :rtype: list[str]
+
+ .. versionadded:: 0.1.0
+ """
+ returnlist(self.xa_elem.arrayByApplyingSelector_("name"))
+
+
[docs]defcontainer(self)->list[Union[XABikeDocument,'XABikeRow']]:
+ """Gets the container of each row in the list.
+
+ :return: A list of row containers
+ :rtype: list[Union[XABikeDocument, 'XABikeRow']]
+
+ .. versionadded:: 0.1.0
+ """
+ return[x.containerforxinself]
+
+
[docs]defcontainer_row(self)->'XABikeRowList':
+ """Gets the container row of each row in the list.
+
+ :return: A list of row container rows
+ :rtype: XABikeRowList
+
+ .. versionadded:: 0.1.0
+ """
+ ls=self.xa_elem.arrayByApplyingSelector_("containerRow")
+ returnself._new_element(ls,XABikeRowList)
+
+
[docs]defprev_sibling_row(self)->'XABikeRowList':
+ """Gets the previous sibling row of each row in the list.
+
+ :return: A list of row previous sibling rows
+ :rtype: XABikeRowList
+
+ .. versionadded:: 0.1.0
+ """
+ ls=self.xa_elem.arrayByApplyingSelector_("prevSiblingRow")
+ returnself._new_element(ls,XABikeRowList)
+
+
[docs]defnext_sibling_row(self)->'XABikeRowList':
+ """Gets the next sibling row of each row in the list.
+
+ :return: A list of row next sibling rows
+ :rtype: XABikeRowList
+
+ .. versionadded:: 0.1.0
+ """
+ ls=self.xa_elem.arrayByApplyingSelector_("nextSiblingRow")
+ returnself._new_element(ls,XABikeRowList)
+
+
[docs]defentire_contents(self)->'XABikeRowList':
+ """Gets the all contained rows of each row in the list.
+
+ :return: A list of contained rows
+ :rtype: XABikeRowList
+
+ .. versionadded:: 0.1.0
+ """
+ ls=self.xa_elem.arrayByApplyingSelector_("entireContents")
+ ls=[itemforcontentsinlsforitemincontents]
+ returnself._new_element(ls,XABikeRowList)
+
+
[docs]defvisible(self)->list[bool]:
+ """Gets the visible status of each row in the list.
+
+ :return: A list of row visible status booleans
+ :rtype: list[bool]
+
+ .. versionadded:: 0.1.0
+ """
+ returnlist(self.xa_elem.arrayByApplyingSelector_("visible"))
+
+
[docs]defselected(self)->list[bool]:
+ """Gets the selected status of each row in the list.
+
+ :return: A list of row selected status booleans
+ :rtype: list[bool]
+
+ .. versionadded:: 0.1.0
+ """
+ returnlist(self.xa_elem.arrayByApplyingSelector_("selected"))
+
+
[docs]defexpanded(self)->list[bool]:
+ """Gets the expanded status of each row in the list.
+
+ :return: A list of row expanded status booleans
+ :rtype: list[bool]
+
+ .. versionadded:: 0.1.0
+ """
+ returnlist(self.xa_elem.arrayByApplyingSelector_("expanded"))
+
+
[docs]defcollapsed(self)->list[bool]:
+ """Gets the collapsed status of each row in the list.
+
+ :return: A list of row collapsed status booleans
+ :rtype: list[bool]
+
+ .. versionadded:: 0.1.0
+ """
+ returnlist(self.xa_elem.arrayByApplyingSelector_("collapsed"))
+
+
[docs]defby_id(self,id:str)->Union['XABikeRow',None]:
+ """Retrieves the row whose ID matches the given ID, if one exists.
+
+ :return: The desired row, if it is found
+ :rtype: Union[XABikeRow, None]
+
+ .. versionadded:: 0.1.0
+ """
+ returnself.by_property("id",id)
+
+
[docs]defby_url(self,url:Union[str,XABase.XAURL])->Union['XABikeRow',None]:
+ """Retrieves the row whose URL matches the given URL, if one exists.
+
+ :return: The desired row, if it is found
+ :rtype: Union[XABikeRow, None]
+
+ .. versionadded:: 0.1.0
+ """
+ ifisinstance(url,XABase.XAURL):
+ url=url.url
+ returnself.by_property("url",url)
+
+
[docs]defby_level(self,level:int)->Union['XABikeRow',None]:
+ """Retrieves the first row whose level matches the given level, if one exists.
+
+ :return: The desired row, if it is found
+ :rtype: Union[XABikeRow, None]
+
+ .. versionadded:: 0.1.0
+ """
+ returnself.by_property("level",level)
+
+
[docs]defby_contains_rows(self,contains_rows:bool)->Union['XABikeRow',None]:
+ """Retrieves the first row whose contains rows status matches the given boolean value, if one exists.
+
+ :return: The desired row, if it is found
+ :rtype: Union[XABikeRow, None]
+
+ .. versionadded:: 0.1.0
+ """
+ returnself.by_property("containsRows",contains_rows)
+
+
[docs]defby_name(self,name:str)->Union['XABikeRow',None]:
+ """Retrieves the row whose name matches the given name, if one exists.
+
+ :return: The desired row, if it is found
+ :rtype: Union[XABikeRow, None]
+
+ .. versionadded:: 0.1.0
+ """
+ returnself.by_property("name",name)
+
+
[docs]defby_container(self,container:Union[XABikeDocument,'XABikeRow'])->Union['XABikeRow',None]:
+ """Retrieves the first row whose container matches the given container, if one exists.
+
+ :return: The desired row, if it is found
+ :rtype: Union[XABikeRow, None]
+
+ .. versionadded:: 0.1.0
+ """
+ returnself.by_property("container",container.xa_elem)
+
+
[docs]defby_container_row(self,container_row:'XABikeRow')->Union['XABikeRow',None]:
+ """Retrieves the first row whose container row matches the given row, if one exists.
+
+ :return: The desired row, if it is found
+ :rtype: Union[XABikeRow, None]
+
+ .. versionadded:: 0.1.0
+ """
+ returnself.by_property("containerRow",container_row.xa_elem)
+
+
[docs]defby_prev_sibling_row(self,prev_sibling_row:'XABikeRow')->Union['XABikeRow',None]:
+ """Retrieves the row whose previous sibling row matches the given row, if one exists.
+
+ :return: The desired row, if it is found
+ :rtype: Union[XABikeRow, None]
+
+ .. versionadded:: 0.1.0
+ """
+ returnself.by_property("prevSiblingRow",prev_sibling_row.xa_elem)
+
+
[docs]defby_next_sibling_row(self,next_sibling_row:'XABikeRow')->Union['XABikeRow',None]:
+ """Retrieves the row whose next sibling row matches the given row, if one exists.
+
+ :return: The desired row, if it is found
+ :rtype: Union[XABikeRow, None]
+
+ .. versionadded:: 0.1.0
+ """
+ returnself.by_property("nextSiblingRow",next_sibling_row.xa_elem)
+
+
[docs]defby_container_document(self,container_document:XABikeDocument)->Union['XABikeRow',None]:
+ """Retrieves the first row whose container document matches the given document, if one exists.
+
+ :return: The desired row, if it is found
+ :rtype: Union[XABikeRow, None]
+
+ .. versionadded:: 0.1.0
+ """
+ returnself.by_property("containerDocument",container_document.xa_elem)
+
+
[docs]defby_entire_contents(self,entire_contents:Union['XABikeRowList',list['XABikeRow']])->Union['XABikeRow',None]:
+ """Retrieves the row whose entire contents matches the given list of rows, if one exists.
+
+ :return: The desired row, if it is found
+ :rtype: Union[XABikeRow, None]
+
+ .. versionadded:: 0.1.0
+ """
+ ifisinstance(entire_contents,list):
+ entire_contents=[x.xa_elemforxinentire_contents]
+ returnself.by_property("entireContents",entire_contents)
+ else:
+ returnself.by_property("entireContents",entire_contents.xa_elem)
+
+
[docs]defby_visible(self,visible:bool)->Union['XABikeRow',None]:
+ """Retrieves the first row whose visible status matches the given boolean value, if one exists.
+
+ :return: The desired row, if it is found
+ :rtype: Union[XABikeRow, None]
+
+ .. versionadded:: 0.1.0
+ """
+ returnself.by_property("visible",visible)
+
+
[docs]defby_selected(self,selected:bool)->Union['XABikeRow',None]:
+ """Retrieves the first row whose selected status matches the given boolean value, if one exists.
+
+ :return: The desired row, if it is found
+ :rtype: Union[XABikeRow, None]
+
+ .. versionadded:: 0.1.0
+ """
+ returnself.by_property("selected",selected)
+
+
[docs]defby_expanded(self,expanded:bool)->Union['XABikeRow',None]:
+ """Retrieves the first row whose expanded status matches the given boolean value, if one exists.
+
+ :return: The desired row, if it is found
+ :rtype: Union[XABikeRow, None]
+
+ .. versionadded:: 0.1.0
+ """
+ returnself.by_property("expanded",expanded)
+
+
[docs]defby_collapsed(self,collapsed:bool)->Union['XABikeRow',None]:
+ """Retrieves the first row whose collapsed status matches the given boolean value, if one exists.
+
+ :return: The desired row, if it is found
+ :rtype: Union[XABikeRow, None]
+
+ .. versionadded:: 0.1.0
+ """
+ returnself.by_property("collapsed",collapsed)
+
+
[docs]defcollapse(self,all:bool=False):
+ """Collapses all rows in the list, optionally collapsing all of the children as well.
+
+ :param all: Whether to collapse all child rows, defaults to False
+ :type all: bool, optional
+
+ .. versionadded:: 0.1.0
+ """
+ forrowinself.xa_elem:
+ row.collapse_all_([row],all)
+
+
[docs]defexpand(self,all:bool=False):
+ """Expands all rows in the list, optionally expanding all of the children as well.
+
+ :param all: Whether to expand all child rows, defaults to False
+ :type all: bool, optional
+
+ .. versionadded:: 0.1.0
+ """
+ forrowinself.xa_elem:
+ row.expand_all_(row,all)
[docs]classXABikeRow(XABase.XAObject,XADeletable):
+ """A row in an outline.
+
+ .. versionadded:: 0.1.0
+ """
+ def__init__(self,properties):
+ super().__init__(properties)
+
+ self.id:str#: The unique and persistent identifier for the row
+ self.url:XABase.XAURL#: The Bike URL for the row combining the document ID with the item ID
+ self.level:int#: The indentation level for the row in the outline
+ self.contains_rows:bool#: True if the row contains other rows
+ self.name:str#: The plain text content of the row
+ self.container:Union[XABikeRow,XABikeDocument]#: Container of the row
+ self.container_row:XABikeRow#: The row that directly contains this row
+ self.prev_sibling_row:XABikeRow#: The previous row with the same container row as this row
+ self.next_sibling_row:XABikeRow#: The next row with the same container as this row
+ self.container_document:XABikeDocument#: The document that contains this row
+ self.entire_contents:XABikeRowList#: The list of all rows contained by this row
+ self.visible:bool#: True if this row is visible in the window (may require scrolling)
+ self.selected:bool#: True if this row is selected in the window
+ self.expanded:bool#: True if this row is expanded in the window
+ self.collapsed:bool#: True if this row is collapsed in the window
+
+ @property
+ defid(self)->str:
+ returnself.xa_elem.id()
+
+ @property
+ defurl(self)->XABase.XAURL:
+ returnXABase.XAURL(self.xa_elem.url())
+
+ @property
+ deflevel(self)->int:
+ returnself.xa_elem.level()
+
+ @property
+ defcontains_rows(self)->bool:
+ returnself.xa_elem.containsRows()
+
+ @property
+ defname(self)->str:
+ returnself.xa_elem.name()
+
+ @name.setter
+ defname(self,name:str):
+ self.set_property('name',name)
+
+ @property
+ defcontainer(self)->Union['XABikeRow',XABikeDocument]:
+ container=self.xa_elem.container()
+ ifhasattr(container,"level"):
+ returnself._new_element(container,XABikeRow)
+ else:
+ returnself._new_element(container,XABikeDocument)
+
+ @property
+ defcontainer_row(self)->Union['XABikeRow',None]:
+ row=self.xa_elem.containerRow()
+ ifrowisnotNone:
+ returnself._new_element(row,XABikeRow)
+
+ @property
+ defprev_sibling_row(self)->'XABikeRow':
+ returnself._new_element(self.xa_elem.prevSiblingRow(),XABikeRow)
+
+ @property
+ defnext_sibling_row(self)->type:
+ returnself._new_element(self.xa_elem.nextSiblingRow(),XABikeRow)
+
+ @property
+ defcontainer_document(self)->XABikeDocument:
+ returnself._new_element(self.xa_elem.containerDocument(),XABikeDocument)
+
+ @property
+ defentire_contents(self)->XABikeRowList:
+ returnself._new_element(self.xa_elem.entire_contents(),XABikeRowList)
+
+ @property
+ defvisible(self)->bool:
+ returnself.xa_elem.visible()
+
+ @property
+ defselected(self)->bool:
+ returnself.xa_elem.selected()
+
+ @property
+ defexpanded(self)->bool:
+ returnself.xa_elem.expanded()
+
+ @property
+ defcollapsed(self)->bool:
+ returnself.xa_elem.collapsed()
+
+
[docs]defcollapse(self,all:bool=False):
+ """Collapses the row and optionally all rows it contains.
+
+ :param recursive: Whether to also collapse all rows contained by this row, defaults to False
+ :type recursive: bool, optional
+
+ .. versionadded:: 0.1.0
+ """
+ self.xa_elem.collapseAll_(all)
+
+
[docs]defexpand(self,all:bool=False):
+ """Expanded the row and optionally all rows it contains.
+
+ :param recursive: Whether to also expand all rows contained by this row, defaults to False
+ :type recursive: bool, optional
+
+ .. versionadded:: 0.1.0
+ """
+ self.xa_elem.expandAll_(all)
+
+
[docs]defmove_to(self,location:'XABikeRow'):
+ """Makes the row a child of the specified row.
+
+ :param location: The row to move this row to.
+ :type location: XABikeRow
+
+ :Example:
+
+ >>> import PyXA
+ >>> app = PyXA.Application("Bike")
+ >>> doc = app.documents()[0]
+ >>> row1 = doc.rows()[0]
+ >>> row2 = doc.rows()[5]
+ >>> row1.move_to(row2)
+
+ .. versionadded:: 0.1.0
+ """
+ self.xa_elem.moveTo_(location.xa_elem)
+
+ # def duplicate(self, location: Union[XABikeDocument, 'XABikeRow', None] = None, properties: Union[dict, None] = None):
+ # """Duplicates the row either in-place or at a specified location.
+
+ # :param location: The document or row to create a duplicate of this row in, defaults to None (duplicate in-place)
+ # :type location: Union[XABikeDocument, XABikeRow, None], optional
+ # :param properties: Properties to set in the new copy right away, defaults to None (no properties changed)
+ # :type properties: Union[dict, None], options
+ # """
+ # if properties is None:
+ # properties = {}
+
+ # if location is None:
+ # self.xa_elem.duplicateTo_withProperties_(self.xa_elem.containerDocument(), properties)
+ # else:
+ # self.xa_elem.duplicateTo_withProperties_(location.xa_elem, properties)
+
+
[docs]defrows(self,filter:dict=None)->Union['XABikeRowList',None]:
+ """Returns a list of rows, as PyXA-wrapped objects, matching the given filter.
+
+ :param filter: A dictionary specifying property-value pairs that all returned rows will have, or None
+ :type filter: Union[dict, None]
+ :return: The list of rows
+ :rtype: XABikeRowList
+
+ :Example:
+
+ >>> import PyXA
+ >>> app = PyXA.Application("Bike")
+ >>> doc = app.front_window.document
+ >>> row = doc.rows()[4]
+ >>> print(row.rows())
+ <<class 'PyXA.apps.Bike.XABikeRowList'>['Watch intro movie', 'Glance through features list', 'https://www.hogbaysoftware.com/bike']>
+
+ .. versionadded:: 0.1.0
+ """
+ returnself._new_element(self.xa_elem.rows(),XABikeRowList,filter)
+
+
[docs]defattributes(self,filter:dict=None)->Union['XABikeAttributeList',None]:
+ """Returns a list of attributes, as PyXA-wrapped objects, matching the given filter.
+
+ :param filter: A dictionary specifying property-value pairs that all returned attributes will have, or None
+ :type filter: Union[dict, None]
+ :return: The list of attributes
+ :rtype: XABikeAttributeList
+
+ .. versionadded:: 0.1.0
+ """
+ returnself._new_element(self.xa_elem.attributes(),XABikeAttributeList,filter)
[docs]classXABikeAttributeList(XABase.XAList):
+ """A wrapper around a list of attributes.
+
+ All properties of attribute objects can be accessed via methods on the list, returning a list of each attribute's value for the property.
+
+ .. versionadded:: 0.1.0
+ """
+ def__init__(self,properties:dict,filter:Union[dict,None]=None):
+ super().__init__(properties,XABikeAttribute,filter)
+
+
[docs]defname(self)->list[str]:
+ """Gets the name of each attribute in the list.
+
+ :return: A list of attribute names
+ :rtype: list[str]
+
+ .. versionadded:: 0.1.0
+ """
+ returnlist(self.xa_elem.arrayByApplyingSelector_("name"))
+
+
[docs]defvalue(self)->list[str]:
+ """Gets the value of each attribute in the list.
+
+ :return: A list of attribute values
+ :rtype: list[str]
+
+ .. versionadded:: 0.1.0
+ """
+ returnlist(self.xa_elem.arrayByApplyingSelector_("value"))
+
+
[docs]defcontainer_row(self)->XABikeRowList:
+ """Gets the container row of each attribute in the list.
+
+ :return: A list of attribute container rows
+ :rtype: list[str]
+
+ .. versionadded:: 0.1.0
+ """
+ ls=self.xa_elem.arrayByApplyingSelector_("containerRow")
+ returnself._new_element(ls,XABikeRowList)
+
+
[docs]defby_name(self,name:str)->Union['XABikeAttribute',None]:
+ """Retrieves the attribute whose name matches the given name, if one exists.
+
+ :return: The desired attribute, if it is found
+ :rtype: Union[XABikeAttribute, None]
+
+ .. versionadded:: 0.1.0
+ """
+ returnself.by_property("name",name)
+
+
[docs]defby_value(self,value:str)->Union['XABikeAttribute',None]:
+ """Retrieves the first attribute whose value matches the given value, if one exists.
+
+ :return: The desired attribute, if it is found
+ :rtype: Union[XABikeAttribute, None]
+
+ .. versionadded:: 0.1.0
+ """
+ returnself.by_property("value",value)
+
+
[docs]defby_container_row(self,container_row:XABikeRow)->Union['XABikeAttribute',None]:
+ """Retrieves the first attribute whose container row matches the given row, if one exists.
+
+ :return: The desired attribute, if it is found
+ :rtype: Union[XABikeAttribute, None]
+
+ .. versionadded:: 0.1.0
+ """
+ returnself.by_property("containerRow",container_row.xa_elem)
[docs]defcopy_value(self):
+ """Copies the current value of the calculator result. Mimics clicking Edit->Copy.
+
+ .. versionadded:: 0.0.2
+ """
+ self.menu_bars()[0].menu_bar_items()[3].menus()[0].menu_items()[4].press()
+
+ # View Menu
+
[docs]defshow_basic_calculator(self):
+ """Switches the view to the basic calculator. Mimics clicking View->Basic.
+
+ .. versionadded:: 0.0.2
+ """
+ self.menu_bars()[0].menu_bar_items()[4].menus()[0].menu_items()[0].press()
+
+
[docs]defshow_scientific_calculator(self):
+ """Switches the view to the scientific calculator. Mimics clicking View->Scientific.
+
+ .. versionadded:: 0.0.2
+ """
+ self.menu_bars()[0].menu_bar_items()[4].menus()[0].menu_items()[1].press()
+
+
[docs]defshow_programmer_calculator(self):
+ """Switches the view to the programmer calculator. Mimics clicking View->Programmer.
+
+ .. versionadded:: 0.0.2
+ """
+ self.menu_bars()[0].menu_bar_items()[4].menus()[0].menu_items()[2].press()
[docs]defshow_paper_tape(self):
+ """Opens the paper tape window. Mimics clicking Window->Show Paper Tape.
+
+ .. versionadded:: 0.0.2
+ """
+ self.menu_bars()[0].menu_bar_items()[7].menus()[0].menu_items()[6].press()
+
+ # Help Menu
+
[docs]defshow_help(self):
+ """Opens the Calculator help window. Mimics clicking Help->Calculator Help.add()
+
+ .. versionadded:: 0.0.2
+ """
+ self.menu_bars()[0].menu_bar_items()[8].menus()[0].menu_items()[1].press()
+
+ # Actions
+
[docs]defclear_value(self):
+ """Clears the current calculator output. Mimics clicking the "C" (clear) button.
+
+ .. versionadded:: 0.0.2
+ """
+ ifself.xa_btnsisNone:
+ self.__load_buttons()
+ self.xa_btns["c"].press()
+
+
[docs]definput(self,sequence:str):
+ """Inputs a sequence of numbers and operations into the calculator by mimicking button clicks.
+
+ This method does not obtain the result of the input. For that, use :func:`current_value`.
+
+ The sequence should be a continuous string (no spaces). The valid characters are numbers `0-9`, `+`, `-`, `*`, `/`, `%`, `~`, `=`, and `c`. Their meanings are as follows:
+
+ - `+`, `-`, `*`, and `/` correspond to their usual operation buttons.
+ - `%` designates the percentage button.
+ - `~` corresponds to the negation button.
+ - `=` represents the equals button.
+ - `c` denotes the clear button.
+
+ :param sequence: The sequence of numbers and operations to execute.
+ :type sequence: str
+
+ :Example:
+
+ >>> import PyXA
+ >>> app = PyXA.application("Calculator")
+ >>> app.input("c2*3.14*5*5=")
+ 34.54
+
+ .. versionadded:: 0.0.2
+ """
+ ifself.xa_btnsisNone:
+ self.__load_buttons()
+ forsymbolinsequence:
+ self.xa_btns[symbol].press()
+
+ # Misc Methods
+
[docs]defcurrent_value(self)->float:
+ """Retrieves the current value of the calculator output.
+
+ :return: The calculator's current displayed value
+ :rtype: float
+
+ .. versionadded:: 0.0.2
+ """
+ returnfloat(self.front_window.groups()[0].static_texts()[0].value.get())
+
+
+
+
+
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/docs/_modules/PyXA/apps/Calculator.html b/docs/_modules/PyXA/apps/Calculator.html
index 90c7189..50f91bc 100644
--- a/docs/_modules/PyXA/apps/Calculator.html
+++ b/docs/_modules/PyXA/apps/Calculator.html
@@ -3,7 +3,7 @@
- PyXA.apps.Calculator — PyXA 0.0.9 documentation
+ PyXA.apps.Calculator — PyXA 0.1.0 documentation
@@ -14,7 +14,9 @@
+
+
@@ -232,7 +234,7 @@
[docs]classXACalendarApplication(XABaseScriptable.XASBApplication,XACanOpenPath):
+ """A class for managing and interacting with scripting elements of the macOS Calendar application.
+
+ .. seealso:: Classes :class:`XACalendarCalendar`, :class:`XACalendarEvent`
+
+ .. versionadded:: 0.0.1
+ """
+
[docs]classParticipationStatus(Enum):
+ """Event participation statuses.
+ """
+ UNKNOWN=XABase.OSType('E6na')#: No answer yet
+ ACCEPTED=XABase.OSType('E6ap')#: Invitation has been accepted
+ DECLINED=XABase.OSType('E6dp')#: Invitation has been declined
+ TENTATIVE=XABase.OSType('E6tp')#: Invitation has been tentatively accepted
+
+
[docs]classEventStatus(Enum):
+ """Event confirmation statuses.
+ """
+ CANCELLED=XABase.OSType('E4ca')#: A cancelled event
+ CONFIRMED=XABase.OSType('E4cn')#: A confirmed event
+ NONE=XABase.OSType('E4no')#: An event without a status
+ TENTATIVE=XABase.OSType('E4te')#: A tentative event
+
+
[docs]classPriority(Enum):
+ """Event priorities.
+ """
+ NONE=XABase.OSType('tdp0')#: No priority assigned
+ LOW=XABase.OSType('tdp9')#: Low priority
+ MEDIUM=XABase.OSType('tdp5')#: Medium priority
+ HIGH=XABase.OSType('tdp1')#: High priority
+
+
[docs]classViewType(Enum):
+ """Views in Calendar.app.
+ """
+ DAY=XABase.OSType('E5da')#: The iCal day view
+ WEEK=XABase.OSType('E5we')#: The iCal week view
+ MONTH=XABase.OSType('E5mo')#: The iCal month view
+ YEAR=XABase.OSType('E5ye')#: The iCal year view
+
+ def__init__(self,properties:dict):
+ super().__init__(properties)
+ self.xa_wcls=XACalendarWindow
+ self.xa_estr=self._exec_suppresed(EventKit.EKEventStore.alloc().init)
+
+ self.properties:dict#: All properties of the application
+ self.name:str#: The name of the application
+ self.frontmost:bool#: Whether Calendar is the frontmost application
+ self.version:str#: The version of the Calendar application
+ self.default_calendar:XACalendarCalendar#: The calendar that events are added to by default
+
+ @property
+ defproperties(self)->dict:
+ returnself.xa_scel.properties()
+
+ @property
+ defname(self)->str:
+ returnself.xa_scel.name()
+
+ @property
+ deffrontmost(self)->bool:
+ returnself.xa_scel.frontmost()
+
+ @frontmost.setter
+ deffrontmost(self,frontmost:bool):
+ self.set_property('frontmost',frontmost)
+
+ @property
+ defversion(self)->str:
+ returnself.xa_scel.version()
+
+ @property
+ defdefault_calendar(self)->'XACalendarCalendar':
+ calendar_obj=self.xa_estr.defaultCalendarForNewEvents()
+ returnself.calendars().by_name(calendar_obj.title())
+
+
[docs]defreload_calendars(self)->'XACalendarApplication':
+ """Reloads the contents of all calendars.
+
+ :return: The application object
+ :rtype: XACalendarApplication
+
+ .. versionadded:: 0.0.1
+ """
+ self.xa_scel.reloadCalendars()
+ returnself
[docs]defview_calendar_at(self,date:datetime,view:Union[None,'XACalendarApplication.ViewType']=None)->'XACalendarApplication':
+ """Displays the calendar at the provided date.
+
+ :param date: The date to display.
+ :type date: datetime
+ :return: A reference to the Calendar application object.
+ :rtype: XACalendarApplication
+
+ :Example:
+
+ >>> import PyXA
+ >>> from datetime import date
+ >>> app = PyXA.application("Calendar")
+ >>> date1 = date(2022, 7, 20)
+ >>> app.view_calendar_at(date1)
+
+ .. versionadded:: 0.0.1
+ """
+ ifviewisNone:
+ self.xa_estr.showDateInCalendar_inView_(date,1)
+ elifview==XACalendarApplication.ViewType.YEAR:
+ self.xa_estr.showDateInCalendar_inView_(date,3)
+ else:
+ self.xa_estr.showDateInCalendar_inView_(date,0)
+ self.xa_scel.switchViewTo_(view.value)
+ returnself
+
+
[docs]defsubscribe_to(self,url:str)->'XACalendarCalendar':
+ """Subscribes to the calendar at the specified URL.
+
+ :param url: The URL of the calendar (in iCal format) to subscribe to
+ :type url: str
+ :return: The newly created calendar object
+ :rtype: XACalendarCalendar
+
+ .. versionadded:: 0.0.1
+ """
+ self.xa_scel.GetURL_(url)
+ returnself.calendars()[-1]
+
+
[docs]defdocuments(self,filter:Union[dict,None]=None)->'XACalendarDocumentList':
+ """Returns a list of documents, as PyXA objects, matching the given filter.
+
+ :param filter: A dictionary specifying property-value pairs that all returned documents will have, or None
+ :type filter: Union[dict, None]
+ :return: The list of documents
+ :rtype: XARemindersDocumentList
+
+ .. versionadded:: 0.0.6
+ """
+ returnself._new_element(self.xa_scel.documents(),XACalendarDocumentList,filter)
+
+
[docs]defcalendars(self,filter:Union[dict,None]=None)->'XACalendarCalendarList':
+ """Returns a list of calendars, as PyXA objects, matching the given filter.
+
+ :param filter: A dictionary specifying property-value pairs that all returned calendars will have, or None
+ :type filter: Union[dict, None]
+ :return: The list of calendars
+ :rtype: XACalendarCalendarList
+
+ :Example 1: Get all calendars
+
+ >>> import PyXA
+ >>> app = PyXA.application("Calendar")
+ >>> print(app.calendars())
+ <<class 'PyXA.apps.Calendar.XACalendarCalendarList'>['Calendar', 'Calendar2', 'Calendar3', ...]>
+
+ :Example 2: Get calendars using a filter
+
+ >>> import PyXA
+ >>> app = PyXA.application("Calendar")
+ >>> print(app.calendars({"name": "Calendar"})[0])
+ <<class 'PyXA.apps.Calendar.XACalendarCalendar'>Calendar>
+
+ :Example 3: Get calendars using list methods
+
+ >>> import PyXA
+ >>> app = PyXA.application("Calendar")
+ >>> print(app.calendars().by_name("Calendar"))
+ <<class 'PyXA.apps.Calendar.XACalendarCalendar'>Calendar>
+
+ .. versionadded:: 0.0.6
+ """
+ returnself._new_element(self.xa_scel.calendars(),XACalendarCalendarList,filter)
+
+
[docs]defnew_calendar(self,name:str="New Calendar")->'XACalendarCalendar':
+ """Creates a new calendar with the given name.
+
+ :param name: The name of the calendar, defaults to "New Calendar"
+ :type name: str, optional
+ :return: The newly created calendar object
+ :rtype: XACalendarCalendar
+
+ :Example:
+
+ >>> import PyXA
+ >>> app = PyXA.application("Calendar")
+ >>> app.new_calendar("PyXA Development")
+
+ .. versionadded:: 0.0.1
+ """
+ new_calendar=self.make("calendar",{"name":name})
+ self.calendars().push(new_calendar)
+
+ desc=new_calendar.xa_elem.description()
+ id=desc[desc.index("id")+4:desc.index("of app")-3]
+ returnreversed(self.calendars()).by_name(name)
+
+
[docs]defnew_event(self,summary:str,start_date:datetime,end_date:datetime,calendar:Union['XACalendarCalendar',None]=None)->'XACalendarEvent':
+ """Creates a new event with the given name and start/end dates in the specified calendar. If no calendar is specified, the default calendar is used.
+
+ :param name: The name of the event
+ :type name: str
+ :param start_date: The start date and time of the event.
+ :type start_date: datetime
+ :param end_date: The end date and time of the event.
+ :type end_date: datetime
+ :return: A reference to the newly created event.
+ :rtype: XACalendarEvent
+
+ :Example: Create event on the default calendar
+
+ >>> from datetime import datetime, timedelta
+ >>> import PyXA
+ >>> app = PyXA.application("Calendar")
+ >>> start_date = datetime.now()
+ >>> end_date = start_date + timedelta(hours = 1)
+ >>> app.new_event("Learn about PyXA", start_date, end_date)
+
+ :Example: Create event on a specific calendar
+
+ >>> from datetime import datetime, timedelta
+ >>> import PyXA
+ >>> app = PyXA.application("Calendar")
+ >>> start_date = datetime.now()
+ >>> end_date = start_date + timedelta(hours = 1)
+ >>> calendar = app.calendars()[-1]
+ >>> app.new_event("Learn about PyXA", start_date, end_date, calendar)
+
+ .. versionadded:: 0.0.1
+ """
+ ifcalendarisNone:
+ calendar=self.default_calendar
+ new_event=self.make("event",{"summary":summary,"startDate":start_date,"endDate":end_date})
+ calendar.events().push(new_event)
+ returncalendar.events().by_uid(new_event.uid)
+
+
[docs]defmake(self,specifier:str,properties:dict=None):
+ """Creates a new element of the given specifier class without adding it to any list.
+
+ Use :func:`XABase.XAList.push` to push the element onto a list.
+
+ :param specifier: The classname of the object to create
+ :type specifier: str
+ :param properties: The properties to give the object
+ :type properties: dict
+ :return: A PyXA wrapped form of the object
+ :rtype: XABase.XAObject
+
+ :Example 1: Make a new calendar
+
+ >>> import PyXA
+ >>> app = PyXA.application("Calendar")
+ >>> new_calendar = app.make("calendar", {"name": "PyXA Development"})
+ >>> app.calendars().push(new_calendar)
+
+ :Example 2: Make a new event
+
+ >>> import PyXA
+ >>> app = PyXA.application("Calendar")
+ >>> start_date = datetime.now()
+ >>> end_date = start_date + timedelta(hours = 1)
+ >>> new_event = app.make("event", {"summary": "Work on PyXA", "startDate": start_date, "endDate": end_date})
+ >>> app.default_calendar.events().push(new_event)
+
+ .. versionadded:: 0.0.6
+ """
+ ifpropertiesisNone:
+ properties={}
+
+ obj=self.xa_scel.classForScriptingClass_(specifier).alloc().initWithProperties_(properties)
+
+ ifspecifier=="document":
+ returnself._new_element(obj,XACalendarDocument)
+ elifspecifier=="calendar":
+ returnself._new_element(obj,XACalendarCalendar)
+ elifspecifier=="event":
+ returnself._new_element(obj,XACalendarEvent)
+ elifspecifier=="displayAlarm":
+ returnself._new_element(obj,XACalendarDisplayAlarm)
+ elifspecifier=="mailAlarm":
+ returnself._new_element(obj,XACalendarMailAlarm)
+ elifspecifier=="soundAlarm":
+ returnself._new_element(obj,XACalendarSoundAlarm)
+ elifspecifier=="openFileAlarm":
+ returnself._new_element(obj,XACalendarOpenFileAlarm)
+
+
+
+
+
[docs]classXACalendarWindow(XABaseScriptable.XASBWindow):
+ """A window of Calendar.app.
+
+ .. versionadded:: 0.0.1
+ """
+ def__init__(self,properties:dict):
+ super().__init__(properties)
+ self.properties:dict#: All properties of the window
+ self.name:str#: The name of the window
+ self.id:str#: The unique identifier for the window
+ self.index:int#: The index of the window in the front-to-back ordering
+ self.bounds:Tuple[int,int,int,int]#: The bounding rectangle of the window
+ self.closeable:bool#: Whether the window has a close button
+ self.miniaturizable:bool#: Whether the window can be minimized
+ self.miniaturized:bool#: Whether the window is currently minimized
+ self.resizable:bool#: Whether the window can be resized
+ self.visible:bool#: Whether the window is currently visible
+ self.zoomable:bool#: Whether the window can be zoomed
+ self.zoomed:bool#: Whether the window is currently zoomed
+ self.document:XACalendarDocument#: The current document displayed in the window
+
+ @property
+ defproperties(self)->dict:
+ returnself.xa_elem.properties()
+
+ @property
+ defname(self)->str:
+ returnself.xa_elem.name()
+
+ @property
+ defid(self)->str:
+ returnself.xa_elem.id()
+
+ @property
+ defindex(self)->int:
+ returnself.xa_elem.index()
+
+ @index.setter
+ defindex(self,index:int):
+ self.set_property('index',index)
+
+ @property
+ defbounds(self)->Tuple[int,int,int,int]:
+ rect=self.xa_elem.bounds()
+ origin=rect.origin
+ size=rect.size
+ return(origin.x,origin.y,size.width,size.height)
+
+ @bounds.setter
+ defbounds(self,bounds:Tuple[int,int,int,int]):
+ x=bounds[0]
+ y=bounds[1]
+ w=bounds[2]
+ h=bounds[3]
+ value=AppKit.NSValue.valueWithRect_(AppKit.NSMakeRect(x,y,w,h))
+ self.set_property("bounds",value)
+
+ @property
+ defcloseable(self)->bool:
+ returnself.xa_elem.closeable()
+
+ @property
+ defminiaturizable(self)->bool:
+ returnself.xa_elem.miniaturizable()
+
+ @property
+ defminiaturized(self)->bool:
+ returnself.xa_elem.miniaturized()
+
+ @miniaturized.setter
+ defminiaturized(self,miniaturized:bool):
+ self.set_property('miniaturized',miniaturized)
+
+ @property
+ defresizable(self)->bool:
+ returnself.xa_elem.resizable()
+
+ @property
+ defvisible(self)->bool:
+ returnself.xa_elem.visible()
+
+ @visible.setter
+ defvisible(self,visible:bool):
+ self.set_property('visible',visible)
+
+ @property
+ defzoomable(self)->bool:
+ returnself.xa_elem.zoomable()
+
+ @property
+ defzoomed(self)->bool:
+ returnself.xa_elem.zoomed()
+
+ @zoomed.setter
+ defzoomed(self,zoomed:bool):
+ self.set_property('zoomed',zoomed)
+
+ @property
+ defdocument(self)->'XACalendarDocument':
+ returnself._new_element(self.xa_elem.document(),XACalendarDocument)
+
+
+
+
+
[docs]classXACalendarDocumentList(XABase.XAList):
+ """A wrapper around lists 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.
+
+ .. versionadded:: 0.0.6
+ """
+ def__init__(self,properties:dict,filter:Union[dict,None]=None):
+ super().__init__(properties,XACalendarDocument,filter)
+
+
[docs]defproperties(self)->List[dict]:
+ """Gets the properties of each document in the list.
+
+ :return: A list of document properties dictionaries
+ :rtype: List[dict]
+
+ .. versionadded:: 0.0.6
+ """
+ returnlist(self.xa_elem.arrayByApplyingSelector_("properties"))
+
+
[docs]defname(self)->List[str]:
+ """Gets the name of each document in the list.
+
+ :return: A list of document names
+ :rtype: List[str]
+
+ .. versionadded:: 0.0.6
+ """
+ returnlist(self.xa_elem.arrayByApplyingSelector_("name"))
+
+
[docs]defmodified(self)->List[bool]:
+ """Gets the modified status of each document in the list.
+
+ :return: A list of document modified status boolean values
+ :rtype: List[bool]
+
+ .. versionadded:: 0.0.6
+ """
+ returnlist(self.xa_elem.arrayByApplyingSelector_("modified"))
+
+
[docs]deffile(self)->List[XABase.XAPath]:
+ """Gets the file path of each document in the list.
+
+ :return: A list of document file paths
+ :rtype: List[XABase.XAPath]
+
+ .. versionadded:: 0.0.6
+ """
+ ls=self.xa_elem.arrayByApplyingSelector_("file")
+ return[XABase.XAPath(x)forxinls]
+
+
[docs]defby_properties(self,properties:dict)->Union['XACalendarDocument',None]:
+ """Retrieves the document whose properties matches the given properties dictionary, if one exists.
+
+ :return: The desired document, if it is found
+ :rtype: Union[XACalendarDocument, None]
+
+ .. versionadded:: 0.0.6
+ """
+ returnself.by_property("properties",properties)
+
+
[docs]defby_name(self,name:str)->Union['XACalendarDocument',None]:
+ """Retrieves the document whose name matches the given name, if one exists.
+
+ :return: The desired document, if it is found
+ :rtype: Union[XACalendarDocument, None]
+
+ .. versionadded:: 0.0.6
+ """
+ returnself.by_property("name",name)
+
+
[docs]defby_modified(self,modified:bool)->Union['XACalendarDocument',None]:
+ """Retrieves the document whose modified status matches the given boolean value, if one exists.
+
+ :return: The desired document, if it is found
+ :rtype: Union[XACalendarDocument, None]
+
+ .. versionadded:: 0.0.6
+ """
+ returnself.by_property("modified",modified)
+
+
[docs]defby_file(self,file:XABase.XAPath)->Union['XACalendarDocument',None]:
+ """Retrieves the document whose file matches the given file path, if one exists.
+
+ :return: The desired document, if it is found
+ :rtype: Union[XACalendarDocument, None]
+
+ .. versionadded:: 0.0.6
+ """
+ returnself.by_property("file",file.xa_elem)
[docs]classXACalendarDocument(XABase.XAObject):
+ """A document in Calendar.app.
+
+ .. versionadded:: 0.0.6
+ """
+ def__init__(self,properties:dict):
+ super().__init__(properties)
+ self.properties:dict#: All properties of the document
+ self.name:str#: The name of the document
+ self.modified:bool#: Whether the document has been modified since it was last saved
+ self.file:XABase.XAPath#: The location of the document on disk, if it has one
+
+ @property
+ defproperties(self)->dict:
+ returnself.xa_elem.properties()
+
+ @property
+ defname(self)->str:
+ returnself.xa_elem.name()
+
+ @property
+ defmodified(self)->bool:
+ returnself.xa_elem.modified()
+
+ @property
+ deffile(self)->XABase.XAPath:
+ returnXABase.XAPath(self.xa_elem.file())
+
+
+
+
+
[docs]classXACalendarCalendarList(XABase.XAList):
+ """A wrapper around lists of calendars that employs fast enumeration techniques.
+
+ All properties of calendars can be called as methods on the wrapped list, returning a list containing each calendar's value for the property.
+
+ .. versionadded:: 0.0.6
+ """
+ def__init__(self,properties:dict,filter:Union[dict,None]=None):
+ super().__init__(properties,XACalendarCalendar,filter)
+
+
[docs]defproperties(self)->List[dict]:
+ """Gets the properties of each calendar in the list.
+
+ :return: A list of calendar properties dictionaries
+ :rtype: List[dict]
+
+ .. versionadded:: 0.0.6
+ """
+ returnlist(self.xa_elem.arrayByApplyingSelector_("properties"))
+
+
[docs]defname(self)->List[str]:
+ """Gets the name of each calendar in the list.
+
+ :return: A list of calendar names
+ :rtype: List[str]
+
+ .. versionadded:: 0.0.6
+ """
+ returnlist(self.xa_elem.arrayByApplyingSelector_("name"))
+
+
[docs]defcolor(self)->List[str]:
+ """Gets the color of each calendar in the list.
+
+ :return: A list of calendar color strings
+ :rtype: List[str]
+
+ .. versionadded:: 0.0.6
+ """
+ ls=self.xa_elem.arrayByApplyingSelector_("color")
+ return[XABase.XAColor(x)forxinls]
+
+
[docs]defcalendar_identifier(self)->List[str]:
+ """Gets the ID of each calendar in the list.
+
+ :return: A list of calendar IDs
+ :rtype: List[str]
+
+ .. versionadded:: 0.0.6
+ """
+ returnlist(self.xa_elem.arrayByApplyingSelector_("calendarIdentifier"))
+
+
[docs]defwritable(self)->List[bool]:
+ """Gets the writable status of each calendar in the list.
+
+ :return: A list of calendar writable status boolean values
+ :rtype: List[bool]
+
+ .. versionadded:: 0.0.6
+ """
+ returnlist(self.xa_elem.arrayByApplyingSelector_("writable"))
+
+
[docs]defdescription(self)->List[str]:
+ """Gets the description of each calendar in the list.
+
+ :return: A list of calendar descriptions
+ :rtype: List[str]
+
+ .. versionadded:: 0.0.6
+ """
+ returnlist(self.xa_elem.arrayByApplyingSelector_("description"))
+
+
[docs]defevents(self)->'XACalendarEventList':
+ """Gets the events of each calendar in the list.
+
+ :return: A list of calendar events
+ :rtype: XACalendarEventList
+
+ .. versionadded:: 0.0.6
+ """
+ ls=self.xa_elem.arrayByApplyingSelector_("events")
+ returnself._new_element(ls,XACalendarEventList)
+
+
[docs]defby_properties(self,properties:dict)->Union['XACalendarCalendar',None]:
+ """Retrieves the calendar whose properties matches the given properties dictionary, if one exists.
+
+ :return: The desired calendar, if it is found
+ :rtype: Union[XACalendarCalendar, None]
+
+ .. versionadded:: 0.0.6
+ """
+ returnself.by_property("properties",properties)
+
+
[docs]defby_name(self,name:str)->Union['XACalendarCalendar',None]:
+ """Retrieves the calendar whose name matches the given name, if one exists.
+
+ :return: The desired calendar, if it is found
+ :rtype: Union[XACalendarCalendar, None]
+
+ .. versionadded:: 0.0.6
+ """
+ returnself.by_property("name",name)
+
+
[docs]defby_color(self,color:XABase.XAColor)->Union['XACalendarCalendar',None]:
+ """Retrieves the first calendar whose color matches the given color string, if one exists.
+
+ :return: The desired calendar, if it is found
+ :rtype: Union[XACalendarCalendar, None]
+
+ .. versionadded:: 0.0.6
+ """
+ returnself.by_property("color",color.xa_elem)
+
+
[docs]defby_calendar_identifier(self,calendar_identifier:str)->Union['XACalendarCalendar',None]:
+ """Retrieves the calendar whose ID matches the given ID, if one exists.
+
+ :return: The desired calendar, if it is found
+ :rtype: Union[XACalendarCalendar, None]
+
+ .. versionadded:: 0.0.6
+ """
+ returnself.by_property("calendarIdentifier",calendar_identifier)
+
+
[docs]defby_writable(self,writable:bool)->Union['XACalendarCalendar',None]:
+ """Retrieves the first calendar whose writable status matches the given boolean value, if one exists.
+
+ :return: The desired calendar, if it is found
+ :rtype: Union[XACalendarCalendar, None]
+
+ .. versionadded:: 0.0.6
+ """
+ returnself.by_property("writable",writable)
+
+
[docs]defby_description(self,description:str)->Union['XACalendarCalendar',None]:
+ """Retrieves the calendar whose description matches the given description string, if one exists.
+
+ :return: The desired calendar, if it is found
+ :rtype: Union[XACalendarCalendar, None]
+
+ .. versionadded:: 0.0.6
+ """
+ forcalendarinself:
+ ifcalendar.description==description:
+ returncalendar
[docs]defevents_in_range(self,start_date:datetime,end_date:datetime)->'XACalendarEventList':
+ """Gets a list of events occurring between the specified start and end datetimes.
+
+ :param start_date: The earliest date an event in the list should begin.
+ :type start_date: datetime
+ :param end_date: The latest date an event in the list should end.
+ :type end_date: datetime
+ :return: The list of events.
+ :rtype: XACalendarEventList
+
+ :Example:
+
+ >>> from datetime import date
+ >>> import PyXA
+ >>> app = PyXA.application("Calendar")
+ >>> calendar = app.default_calendar
+ >>> start_date = date(2022, 6, 4)
+ >>> end_date = date(2022, 6, 6)
+ >>> print(calendar.events_in_range(start_date, end_date))
+ [<PyXA.apps.Calendar.XACalendarEvent object at 0x105b83d90>, <PyXA.apps.Calendar.XACalendarEvent object at 0x105b90bb0>, <PyXA.apps.Calendar.XACalendarEvent object at 0x105b90dc0>]
+
+ .. note::
+
+ Querying events from a wide date range can take significant time. If you are looking for a specific subset of events within a large date range, it *might* be faster to use :func:`events` with a well-constructed filter and then iterate through the resulting array of objects, parsing out events outside of the desired date range.
+
+ .. versionadded:: 0.0.2
+ """
+ predicate=XABase.XAPredicate()
+ predicate.add_geq_condition("startDate",start_date)
+ predicate.add_leq_condition("endDate",end_date)
+ events_in_range=predicate.evaluate(self.xa_elem.events())
+ returnself._new_element(events_in_range,XACalendarEventList)
+
+
[docs]defevents_today(self)->'XACalendarEventList':
+ """Gets a list of all events in the next 24 hours.
+
+ :return: The list of events.
+ :rtype: XACalendarEventList
+
+ .. seealso:: :func:`week_events`
+
+ .. versionadded:: 0.0.2
+ """
+ start_date=datetime.now()
+ end_date=start_date+timedelta(days=1)
+ returnself.events_in_range(start_date,end_date)
+
+
[docs]defweek_events(self)->'XACalendarEventList':
+ """Gets a list of events occurring in the next 7 days.
+
+ :return: The list of events.
+ :rtype: XACalendarEventList
+
+ .. seealso:: :func:`events_today`
+
+ .. versionadded:: 0.0.2
+ """
+ start_date=datetime.now()
+ end_date=start_date+timedelta(days=7)
+ returnself.events_in_range(start_date,end_date)
+
+
[docs]defnew_event(self,name:str,start_date:datetime,end_date:datetime)->'XACalendarEvent':
+ """Creates a new event and pushes it onto this calendar's events array.
+
+ :param name: The name of the event.
+ :type name: str
+ :param start_date: The start date and time of the event.
+ :type start_date: datetime
+ :param end_date: The end date and time of the event.
+ :type end_date: datetime
+ :return: A reference to the newly created event.
+ :rtype: XACalendarEvent
+
+ .. versionadded:: 0.0.1
+ """
+ returnself.xa_prnt.xa_prnt.new_event(name,start_date,end_date,self)
+
+
[docs]defevents(self,filter:Union[dict,None]=None)->'XACalendarEventList':
+ """Returns a list of events, as PyXA objects, matching the given filter.
+
+ :param filter: A dictionary specifying property-value pairs that all returned events will have, or None
+ :type filter: Union[dict, None]
+ :return: The list of events
+ :rtype: XACalendarEventList
+
+ .. versionadded:: 0.0.6
+ """
+ returnself._new_element(self.xa_elem.events(),XACalendarEventList,filter)
[docs]classXACalendarMailAlarm(XACalendarAlarm):
+ """A mail alarm in Calendar.app.
+
+ .. versionadded:: 0.0.6
+ """
+ def__init__(self,properties:dict):
+ super().__init__(properties)
+
+
+
+
+
[docs]classXACalendarSoundAlarm(XACalendarAlarm):
+ """A sound alarm in Calendar.app.
+
+ .. versionadded:: 0.0.6
+ """
+ def__init__(self,properties:dict):
+ super().__init__(properties)
+ self.sound_name:str#: The system sound name to be used for the alarm
+ self.sound_file:str#: The path to the sound file to be used for the alarm
+
+ @property
+ defsound_name(self)->str:
+ returnself.xa_elem.soundName()
+
+ @sound_name.setter
+ defsound_name(self,sound_name:str):
+ self.set_property('soundName',sound_name)
+
+ @property
+ defsound_file(self)->str:
+ returnself.xa_elem.soundFile()
+
+ @sound_file.setter
+ defsound_file(self,sound_file:str):
+ self.set_property('soundFile',sound_file)
+
+
+
+
+
[docs]classXACalendarOpenFileAlarm(XACalendarAlarm):
+ """An open file alarm in Calendar.app.
+
+ .. versionadded:: 0.0.6
+ """
+ def__init__(self,properties:dict):
+ super().__init__(properties)
+ self.file_path:str#: The path to be opened by the alarm
+
+ @property
+ deffile_path(self)->str:
+ returnself.xa_elem.filePath()
+
+ @file_path.setter
+ deffile_path(self,file_path:str):
+ self.set_property('filePath',file_path)
+
+
+
+
+
[docs]classXACalendarAttendeeList(XABase.XAList):
+ """A wrapper around lists of attendees that employs fast enumeration techniques.
+
+ All properties of attendees can be called as methods on the wrapped list, returning a list containing each attendee's value for the property.
+
+ .. versionadded:: 0.0.6
+ """
+ def__init__(self,properties:dict,filter:Union[dict,None]=None):
+ super().__init__(properties,XACalendarEvent,filter)
+
+
[docs]defproperties(self)->List[dict]:
+ """Gets the properties of each attendee in the list.
+
+ :return: A list of attendee properties dictionaries
+ :rtype: List[dict]
+
+ .. versionadded:: 0.0.6
+ """
+ returnlist(self.xa_elem.arrayByApplyingSelector_("properties"))
+
+
[docs]defdisplay_name(self)->List[str]:
+ """Gets the display name of each attendee in the list.
+
+ :return: A list of attendee first and last names
+ :rtype: List[str]
+
+ .. versionadded:: 0.0.6
+ """
+ returnlist(self.xa_elem.arrayByApplyingSelector_("displayName"))
+
+
[docs]defemail(self)->List[str]:
+ """Gets the email address of each attendee in the list.
+
+ :return: A list of attendee email addresses
+ :rtype: List[str]
+
+ .. versionadded:: 0.0.6
+ """
+ returnlist(self.xa_elem.arrayByApplyingSelector_("email"))
+
+
[docs]defparticipation_status(self)->List[XACalendarApplication.ParticipationStatus]:
+ """Gets the participation status of each attendee in the list.
+
+ :return: A list of attendee participation statuses
+ :rtype: List[XACalendarApplication.ParticipationStatus]
+
+ .. versionadded:: 0.0.6
+ """
+ ls=self.xa_elem.arrayByApplyingSelector_("participationStatus")
+ return[XACalendarApplication.ParticipationStatus(XABase.OSType(x.stringValue()))forxinls]
+
+
[docs]defby_properties(self,properties:dict)->Union['XACalendarAttendee',None]:
+ """Retrieves the attendee whose properties matches the given properties dictionary, if one exists.
+
+ :return: The desired attendee, if it is found
+ :rtype: Union[XACalendarAttendee, None]
+
+ .. versionadded:: 0.0.6
+ """
+ returnself.by_property("properties",properties)
+
+
[docs]defby_display_name(self,display_name:str)->Union['XACalendarAttendee',None]:
+ """Retrieves the attendee whose display name matches the given first and last names, if one exists.
+
+ :return: The desired attendee, if it is found
+ :rtype: Union[XACalendarAttendee, None]
+
+ .. versionadded:: 0.0.6
+ """
+ returnself.by_property("displayName",display_name)
+
+
[docs]defby_email(self,email:str)->Union['XACalendarAttendee',None]:
+ """Retrieves the attendee whose email address matches the given email address, if one exists.
+
+ :return: The desired attendee, if it is found
+ :rtype: Union[XACalendarAttendee, None]
+
+ .. versionadded:: 0.0.6
+ """
+ returnself.by_property("email",email)
+
+
[docs]defby_participation_status(self,participation_status:XACalendarApplication.ParticipationStatus)->Union['XACalendarAttendee',None]:
+ """Retrieves the attendee whose participation status matches the given status, if one exists.
+
+ :return: The desired attendee, if it is found
+ :rtype: Union[XACalendarAttendee, None]
+
+ .. versionadded:: 0.0.6
+ """
+ returnself.by_property("participationStatus",participation_status.value)
[docs]classXACalendarAttendee(XABase.XAObject):
+ """An event attendee in Calendar.app.
+
+ .. versionadded:: 0.0.1
+ """
+ def__init__(self,properties:dict):
+ super().__init__(properties)
+ self.properties:dict#: All properties of the attendee
+ self.display_name:str#: The first and last name of the attendee
+ self.email:str#: The email address of the attendee
+ self.participation_status:XACalendarApplication.ParticipationStatus#: The invitation status for the attendee
+
+ @property
+ defproperties(self)->dict:
+ returnself.xa_elem.properties()
+
+ @property
+ defdisplay_name(self)->str:
+ returnself.xa_elem.displayName()
+
+ @property
+ defemail(self)->str:
+ returnself.xa_elem.email()
+
+ @property
+ defparticipation_status(self)->XACalendarApplication.ParticipationStatus:
+ returnXACalendarApplication.ParticipationStatus(self.xa_elem.participationStatus())
+
+
+
+
+
[docs]classXACalendarEventList(XABase.XAList):
+ """A wrapper around lists of events that employs fast enumeration techniques.
+
+ All properties of events can be called as methods on the wrapped list, returning a list containing each event's value for the property.
+
+ .. versionadded:: 0.0.6
+ """
+ def__init__(self,properties:dict,filter:Union[dict,None]=None):
+ super().__init__(properties,XACalendarEvent,filter)
+
+ defproperties(self)->List[dict]:
+ """Gets the properties of each event in the list.
+
+ :return: A list of event properties dictionaries
+ :rtype: List[dict]
+
+ .. versionadded:: 0.0.6
+ """
+ returnlist(self.xa_elem.arrayByApplyingSelector_("properties"))
+
+
[docs]defdescription(self)->List[str]:
+ """Gets the description of each event in the list.
+
+ :return: A list of event descriptions
+ :rtype: List[str]
+
+ .. versionadded:: 0.0.6
+ """
+ returnlist(self.xa_elem.arrayByApplyingSelector_("description"))
+
+
[docs]defstart_date(self)->List[datetime]:
+ """Gets the start date of each event in the list.
+
+ :return: A list of event start dates
+ :rtype: List[datetime]
+
+ .. versionadded:: 0.0.6
+ """
+ returnlist(self.xa_elem.arrayByApplyingSelector_("startDate"))
+
+
[docs]defproperties(self)->List[datetime]:
+ """Gets the end date of each event in the list.
+
+ :return: A list of event end dates
+ :rtype: List[datetime]
+
+ .. versionadded:: 0.0.6
+ """
+ returnlist(self.xa_elem.arrayByApplyingSelector_("endDate"))
+
+
[docs]defallday_event(self)->List[bool]:
+ """Gets the all-day status of each event in the list.
+
+ :return: A list of event all-day status boolean values
+ :rtype: List[bool]
+
+ .. versionadded:: 0.0.6
+ """
+ returnlist(self.xa_elem.arrayByApplyingSelector_("alldayEvent"))
+
+
[docs]defrecurrence(self)->List[str]:
+ """Gets the recurrence string of each event in the list.
+
+ :return: A list of event recurrence strings
+ :rtype: List[str]
+
+ .. versionadded:: 0.0.6
+ """
+ returnlist(self.xa_elem.arrayByApplyingSelector_("recurrence"))
+
+
[docs]defsequence(self)->List[int]:
+ """Gets the version of each event in the list.
+
+ :return: A list of event versions
+ :rtype: List[int]
+
+ .. versionadded:: 0.0.6
+ """
+ returnlist(self.xa_elem.arrayByApplyingSelector_("sequence"))
+
+
[docs]defstamp_date(self)->List[datetime]:
+ """Gets the modification date of each event in the list.
+
+ :return: A list of event modification dates
+ :rtype: List[datetime]
+
+ .. versionadded:: 0.0.6
+ """
+ returnlist(self.xa_elem.arrayByApplyingSelector_("stampDate"))
+
+
[docs]defexcluded_dates(self)->List[List[datetime]]:
+ """Gets the excluded dates of each event in the list.
+
+ :return: A list of event excluded dates
+ :rtype: List[List[datetime]]
+
+ .. versionadded:: 0.0.6
+ """
+ returnlist(self.xa_elem.arrayByApplyingSelector_("excludedDates"))
+
+
[docs]defstatus(self)->List[XACalendarApplication.EventStatus]:
+ """Gets the status of each event in the list.
+
+ :return: A list of event statuses
+ :rtype: List[XACalendarApplication.EventStatus]
+
+ .. versionadded:: 0.0.6
+ """
+ ls=self.xa_elem.arrayByApplyingSelector_("status")
+ return[XACalendarApplication.EventStatus(XABase.OSType(x.stringValue()))forxinls]
+
+
[docs]defsummary(self)->List[str]:
+ """Gets the summary of each event in the list.
+
+ :return: A list of event summaries
+ :rtype: List[str]
+
+ .. versionadded:: 0.0.6
+ """
+ returnlist(self.xa_elem.arrayByApplyingSelector_("summary"))
+
+
[docs]deflocation(self)->List[str]:
+ """Gets the location string of each event in the list.
+
+ :return: A list of event locations
+ :rtype: List[str]
+
+ .. versionadded:: 0.0.6
+ """
+ returnlist(self.xa_elem.arrayByApplyingSelector_("location"))
+
+
[docs]defuid(self)->List[str]:
+ """Gets the unique identifier of each event in the list.
+
+ :return: A list of event IDs
+ :rtype: List[str]
+
+ .. versionadded:: 0.0.6
+ """
+ returnlist(self.xa_elem.arrayByApplyingSelector_("uid"))
+
+
[docs]defurl(self)->List[str]:
+ """Gets the URL associated to each event in the list.
+
+ :return: A list of event URLs
+ :rtype: List[str]
+
+ .. versionadded:: 0.0.6
+ """
+ returnlist(self.xa_elem.arrayByApplyingSelector_("URL"))
+
+
[docs]defby_properties(self,properties:dict)->Union['XACalendarEvent',None]:
+ """Retrieves the event whose properties matches the given properties dictionary, if one exists.
+
+ :return: The desired event, if it is found
+ :rtype: Union[XACalendarEvent, None]
+
+ .. versionadded:: 0.0.6
+ """
+ returnself.by_property("properties",properties)
+
+
[docs]defby_description(self,description:str)->Union['XACalendarEvent',None]:
+ """Retrieves the event whose description matches the given description string, if one exists.
+
+ :return: The desired event, if it is found
+ :rtype: Union[XACalendarEvent, None]
+
+ .. versionadded:: 0.0.6
+ """
+ returnself.by_property("description",description)
+
+
[docs]defby_start_date(self,start_date:datetime)->Union['XACalendarEvent',None]:
+ """Retrieves the first event whose start date matches the given date, if one exists.
+
+ :return: The desired event, if it is found
+ :rtype: Union[XACalendarEvent, None]
+
+ .. versionadded:: 0.0.6
+ """
+ returnself.by_property("startDate",start_date)
+
+
[docs]defby_end_date(self,end_date:datetime)->Union['XACalendarEvent',None]:
+ """Retrieves the first event whose end date matches the given date, if one exists.
+
+ :return: The desired event, if it is found
+ :rtype: Union[XACalendarEvent, None]
+
+ .. versionadded:: 0.0.6
+ """
+ returnself.by_property("endDate",end_date)
+
+
[docs]defby_allday_event(self,allday_event:bool)->Union['XACalendarEvent',None]:
+ """Retrieves the first event whose all-day even status matches the given boolean value, if one exists.
+
+ :return: The desired event, if it is found
+ :rtype: Union[XACalendarEvent, None]
+
+ .. versionadded:: 0.0.6
+ """
+ returnself.by_property("alldayEvent",allday_event)
+
+
[docs]defby_recurrence(self,recurrence:str)->Union['XACalendarEvent',None]:
+ """Retrieves the first event whose recurrence string matches the given string, if one exists.
+
+ :return: The desired event, if it is found
+ :rtype: Union[XACalendarEvent, None]
+
+ .. versionadded:: 0.0.6
+ """
+ returnself.by_property("recurrence",recurrence)
+
+
[docs]defby_sequence(self,sequence:int)->Union['XACalendarEvent',None]:
+ """Retrieves the first event whose sequence (version) matches the given sequence number, if one exists.
+
+ :return: The desired event, if it is found
+ :rtype: Union[XACalendarEvent, None]
+
+ .. versionadded:: 0.0.6
+ """
+ returnself.by_property("sequence",sequence)
+
+
[docs]defby_stamp_date(self,stamp_date:datetime)->Union['XACalendarEvent',None]:
+ """Retrieves the first event whose stamp date matches the given date, if one exists.
+
+ :return: The desired event, if it is found
+ :rtype: Union[XACalendarEvent, None]
+
+ .. versionadded:: 0.0.6
+ """
+ returnself.by_property("stampDate",stamp_date)
+
+
[docs]defby_excluded_dates(self,excluded_dates:List[datetime])->Union['XACalendarEvent',None]:
+ """Retrieves the first event whose excluded dates date matches the given list of dates, if one exists.
+
+ :return: The desired event, if it is found
+ :rtype: Union[XACalendarEvent, None]
+
+ .. versionadded:: 0.0.6
+ """
+ returnself.by_property("excludedDates",excluded_dates)
+
+
[docs]defby_status(self,status:XACalendarApplication.EventStatus)->Union['XACalendarEvent',None]:
+ """Retrieves the first event whose status matches the given status, if one exists.
+
+ :return: The desired event, if it is found
+ :rtype: Union[XACalendarEvent, None]
+
+
+ .. versionadded:: 0.0.6
+ """
+ returnself.by_property("status",status.value)
+
+
[docs]defby_summary(self,summary:str)->Union['XACalendarEvent',None]:
+ """Retrieves the first event whose summary matches the given string, if one exists.
+
+ :return: The desired event, if it is found
+ :rtype: Union[XACalendarEvent, None]
+
+ .. versionadded:: 0.0.6
+ """
+ returnself.by_property("summary",summary)
+
+
[docs]defby_location(self,location:str)->Union['XACalendarEvent',None]:
+ """Retrieves the first event whose location string matches the given location, if one exists.
+
+ :return: The desired event, if it is found
+ :rtype: Union[XACalendarEvent, None]
+
+ .. versionadded:: 0.0.6
+ """
+ returnself.by_property("location",location)
+
+
[docs]defby_uid(self,uid:str)->Union['XACalendarEvent',None]:
+ """Retrieves the event whose unique identifier matches the given ID string, if one exists.
+
+ :return: The desired event, if it is found
+ :rtype: Union[XACalendarEvent, None]
+
+ .. versionadded:: 0.0.6
+ """
+ returnself.by_property("uid",uid)
+
+
[docs]defby_url(self,url:str)->Union['XACalendarEvent',None]:
+ """Retrieves the first event whose associated URL matches the given URL string, if one exists.
+
+ :return: The desired event, if it is found
+ :rtype: Union[XACalendarEvent, None]
+
+ .. versionadded:: 0.0.6
+ """
+ returnself.by_property("URL",url)
[docs]defduplicate(self)->'XACalendarEvent':
+ """Duplicates the event, placing the copy on the same calendar.
+
+ :return:The newly created event object.
+ :rtype: XACalendarEvent
+
+ .. versionadded:: 0.0.1
+ """
+ new_event=self.xa_event_obj.duplicate()
+ self.xa_estr.saveEvent_span_error_(new_event,EventKit.EKSpanThisEvent,None)
+
+
[docs]defduplicate_to(self,calendar:XACalendarCalendar)->'XACalendarEvent':
+ """Duplicates the event, placing the copy on the same calendar.
+
+ :return: The event object that this method was called from
+ :rtype: XACalendarEvent
+
+ :Example: Copy today's event to another calendar
+
+ >>> import PyXA
+ >>> app = PyXA.application("Calendar")
+ >>> calendar = app.default_calendar
+ >>> calendar2 = app.calendars()[2]
+ >>> event = calendar.events_today()[0]
+ >>> event.duplicate_to(calendar2)
+
+ .. seealso:: :func:`duplicate`, :func:`move_to`
+
+ .. versionadded:: 0.0.1
+ """
+ calendars=self.xa_estr.allCalendars()
+ calendar_obj=XABase.XAPredicate.evaluate_with_dict(calendars,{"title":calendar.name})[0]
+
+ self.xa_event_obj.copyToCalendar_withOptions_(calendar_obj,1)
+ self.xa_estr.saveCalendar_commit_error_(calendar_obj,True,None)
+ returnself
+
+
[docs]defmove_to(self,calendar:XACalendarCalendar)->'XACalendarEvent':
+ """Moves this event to the specified calendar.
+
+ :param calendar: The calendar to move the event to.
+ :type calendar: XACalendar
+ :return: A reference to the moved event object.
+ :rtype: XACalendarEvent
+
+ :Example: Move today's event to another calendar
+
+ >>> import PyXA
+ >>> app = PyXA.application("Calendar")
+ >>> calendar = app.default_calendar
+ >>> calendar2 = app.calendars()[2]
+ >>> event = calendar.events_today()[0]
+ >>> event.move_to(calendar2)
+
+ .. seealso:: :func:`duplicate_to`
+
+ .. versionadded:: 0.0.2
+ """
+ self.duplicate_to(calendar)
+ self.delete()
+
+
[docs]defadd_attachment(self,path:str)->'XACalendarEvent':
+ """Adds the file at the specified path as an attachment to the event.
+
+ :param path: The path of the file to attach to the event.
+ :type path: str
+ :return: A reference to this event object.
+ :rtype: XACalendarEvent
+
+ :Example:
+
+ >>> import PyXA
+ >>> app = PyXA.application("Calendar")
+ >>> calendar = app.default_calendar
+ >>> calendar2 = app.calendars()[1]
+ >>> event = calendar.events_today()[0]
+ >>> event.add_attachment("/Users/exampleuser/Image.png")
+
+ .. versionadded:: 0.0.2
+ """
+ file_url=XABase.XAPath(path).xa_elem
+ attachment=EventKit.EKAttachment.alloc().initWithFilepath_(file_url)
+ self.xa_elem.addAttachment_(attachment)
+ self.xa_estr.saveEvent_span_error_(self.xa_event_obj,EventKit.EKSpanThisEvent,None)
+ returnself
+
+
[docs]defattendees(self,filter:Union[dict,None]=None)->'XACalendarAttendeeList':
+ """Returns a list of attendees, as PyXA objects, matching the given filter.
+
+ :param filter: A dictionary specifying property-value pairs that all returned attendees will have, or None
+ :type filter: Union[dict, None]
+ :return: The list of attendees
+ :rtype: XACalendarAttendeeList
+
+ .. versionadded:: 0.0.6
+ """
+ returnself._new_element(self.xa_elem.attendees(),XACalendarAttendeeList,filter)
+
+
[docs]defattachments(self,filter:dict=None)->'XACalendarAttachmentList':
+ """"Returns a list of attachments, as PyXA objects, matching the given filter.
+
+ :return: The list of attachments.
+ :rtype: XACalendarAttachmentList
+
+ .. versionadded:: 0.0.2
+ """
+ returnself._new_element(self.xa_event_obj.attachments(),XACalendarAttachmentList,filter)
[docs]classXACalendarAttachmentList(XABase.XAList):
+ """A wrapper around lists of event attachments that employs fast enumeration techniques.
+
+ All properties of attachments can be called as methods on the wrapped list, returning a list containing each attachment's value for the property.
+
+ .. versionadded:: 0.0.6
+ """
+ def__init__(self,properties:dict,filter:Union[dict,None]=None):
+ super().__init__(properties,XACalendarAttachment,filter)
+
+
[docs]deftype(self)->List[str]:
+ """Gets the type of each attachment in the list.
+
+ :return: A list of attachment types
+ :rtype: List[str]
+
+ .. versionadded:: 0.0.6
+ """
+ returnlist(self.xa_elem.arrayByApplyingSelector_("type"))
+
+
[docs]deffile_name(self)->List[str]:
+ """Gets the file name of each attachment in the list.
+
+ :return: A list of attachment file names
+ :rtype: List[str]
+
+ .. versionadded:: 0.0.6
+ """
+ returnlist(self.xa_elem.arrayByApplyingSelector_("filename"))
+
+
[docs]deffile(self)->List[XABase.XAPath]:
+ """Gets the file path of each attachment in the list.
+
+ :return: A list of attachment file paths
+ :rtype: List[XABase.XAPath]
+
+ .. versionadded:: 0.0.6
+ """
+ ls=self.xa_elem.arrayByApplyingSelector_("file")
+ return[XABase.XAPath(x)forxinls]
+
+
[docs]defurl(self)->List[XABase.XAURL]:
+ """Gets the URL of each attachment in the list.
+
+ :return: A list of attachment file URLs
+ :rtype: List[XABase.XAURL]
+
+ .. versionadded:: 0.0.6
+ """
+ ls=self.xa_elem.arrayByApplyingSelector_("URL")
+ return[XABase.XAURL(x)forxinls]
+
+
[docs]defuuid(self)->List[str]:
+ """Gets the UUID of each attachment in the list.
+
+ :return: A list of attachment UUIDs
+ :rtype: List[str]
+
+ .. versionadded:: 0.0.6
+ """
+ returnlist(self.xa_elem.arrayByApplyingSelector_("uuid"))
+
+
[docs]defby_type(self,type:str)->Union['XACalendarAttachment',None]:
+ """Retrieves the first attachment whose type matches the given type, if one exists.
+
+ :return: The desired attachment, if it is found
+ :rtype: Union[XACalendarAttachment, None]
+
+ .. versionadded:: 0.0.6
+ """
+ returnself.by_property("type",type)
+
+
[docs]defby_file_name(self,file_name:str)->Union['XACalendarAttachment',None]:
+ """Retrieves the first attachment whose file name matches the given file name, if one exists.
+
+ :return: The desired attachment, if it is found
+ :rtype: Union[XACalendarAttachment, None]
+
+ .. versionadded:: 0.0.6
+ """
+ returnself.by_property("filename",file_name)
+
+
[docs]defby_file(self,file:XABase.XAPath)->Union['XACalendarAttachment',None]:
+ """Retrieves the first attachment whose file path matches the given path, if one exists.
+
+ :return: The desired attachment, if it is found
+ :rtype: Union[XACalendarAttachment, None]
+
+ .. versionadded:: 0.0.6
+ """
+ returnself.by_property("file",file.xa_elem)
+
+ defby_url(self,url:XABase.XAURL)->Union['XACalendarAttachment',None]:
+ """Retrieves the first attachment whose URL matches the given URL, if one exists.
+
+ :return: The desired attachment, if it is found
+ :rtype: Union[XACalendarAttachment, None]
+
+ .. versionadded:: 0.0.6
+ """
+ returnself.by_property("URL",url.xa_elem)
+
+
[docs]defby_url(self,uuid:str)->Union['XACalendarAttachment',None]:
+ """Retrieves the attachment whose UUID matches the given UUID, if one exists.
+
+ :return: The desired attachment, if it is found
+ :rtype: Union[XACalendarAttachment, None]
+
+ .. versionadded:: 0.0.6
+ """
+ returnself.by_property("uuid",uuid)
[docs]classXACalendarAttachment(XABase.XAObject):
+ """A class for interacting with calendar event attachments.
+
+ .. versionadded:: 0.0.2
+ """
+ def__init__(self,properties:dict):
+ super().__init__(properties)
+ self.type:str#: The content type of the attachment, e.g. `image/png`
+ self.file_name:str#: The filename of the original document
+ self.file:XABase.XAPath#: The location of the attachment on the local disk
+ self.url:XABase.XAURL#: The iCloud URL of the attachment
+ self.uuid:str#: A unique identifier for the attachment
+
+ @property
+ deftype(self)->str:
+ returnself.xa_elem.contentType()
+
+ @property
+ deffile_name(self)->str:
+ returnself.xa_elem.filenameSuggestedByServer()
+
+ @property
+ deffile(self)->XABase.XAPath:
+ returnXABase.XAPath(self.xa_elem.urlOnDisk())
+
+ @property
+ defurl(self)->XABase.XAURL:
+ returnXABase.XAURL(self.xa_elem.urlOnServer())
+
+ @property
+ defuuid(self)->str:
+ returnself.xa_elem.uuid()
+
+
[docs]defopen(self)->'XACalendarAttachment':
+ """Opens the attachment in its default application.
+
+ :return: A reference to the attachment object.
+ :rtype: XACalendarAttachment
+
+ :Example:
+
+ >>> import PyXA
+ >>> app = PyXA.application("Calendar")
+ >>> calendar = app.default_calendar
+ >>> event = calendar.events_today()[0]
+ >>> event.attachments()[0].open()
+
+ .. versionadded:: 0.0.2
+ """
+ self.xa_wksp.openURL_(self.file)
+ returnself
+
+
+
+
+
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/docs/_modules/PyXA/apps/Calendar.html b/docs/_modules/PyXA/apps/Calendar.html
index 882063c..e96d6a7 100644
--- a/docs/_modules/PyXA/apps/Calendar.html
+++ b/docs/_modules/PyXA/apps/Calendar.html
@@ -3,7 +3,7 @@
- PyXA.apps.Calendar — PyXA 0.0.9 documentation
+ PyXA.apps.Calendar — PyXA 0.1.0 documentation
@@ -14,7 +14,9 @@
+
+
@@ -70,10 +72,10 @@
[docs]classSaveOption(Enum):
- """Options for what to do when calling a save event.
- """
- SAVE_FILE=XABase.OSType('yes ')#: Save the file.
- DONT_SAVE=XABase.OSType('no ')#: Do not save the file.
- ASK=XABase.OSType('ask ')#: Ask the user whether or not to save the file.
-
-
[docs]classPrintSetting(Enum):
- """Options to use when printing.
- """
- STANDARD_ERROR_HANDLING=XABase.OSType('lwst')#: Standard PostScript error handling
- DETAILED_ERROR_HANDLING=XABase.OSType('lwdt')#: print a detailed report of PostScript errors
self.name:str#: The name of the windowself.id:str#: The unique identifier for the windowself.index:int#: The index of the window in the front-to-back ordering
- self.bounds:Tuple[Tuple[int,int],Tuple[int,int]]#: The bounding rectangle of the window
+ self.bounds:tuple[int,int,int,int]#: The bounding rectangle of the windowself.closeable:bool#: Whether the window has a close buttonself.miniaturizable:bool#: Whether the window can be minimizedself.miniaturized:bool#: Whether the window is currently minimized
@@ -436,9 +429,25 @@
[docs]defproperties(self)->list[dict]:"""Gets the properties of each document in the list. :return: A list of document properties dictionaries
- :rtype: List[dict]
+ :rtype: list[dict] .. versionadded:: 0.0.6 """returnlist(self.xa_elem.arrayByApplyingSelector_("properties"))
[docs]defname(self)->list[str]:"""Gets the name of each document in the list. :return: A list of document names
- :rtype: List[str]
+ :rtype: list[str] .. versionadded:: 0.0.6 """returnlist(self.xa_elem.arrayByApplyingSelector_("name"))
[docs]defmodified(self)->list[bool]:"""Gets the modified status of each document in the list. :return: A list of document modified status boolean values
- :rtype: List[bool]
+ :rtype: list[bool] .. versionadded:: 0.0.6 """returnlist(self.xa_elem.arrayByApplyingSelector_("modified"))
[docs]deffile(self)->list[XABase.XAPath]:"""Gets the file path of each document in the list. :return: A list of document file paths
- :rtype: List[XABase.XAPath]
+ :rtype: list[XABase.XAPath] .. versionadded:: 0.0.6 """
@@ -610,62 +631,62 @@
[docs]defproperties(self)->list[dict]:"""Gets the properties of each calendar in the list. :return: A list of calendar properties dictionaries
- :rtype: List[dict]
+ :rtype: list[dict] .. versionadded:: 0.0.6 """returnlist(self.xa_elem.arrayByApplyingSelector_("properties"))
[docs]defname(self)->list[str]:"""Gets the name of each calendar in the list. :return: A list of calendar names
- :rtype: List[str]
+ :rtype: list[str] .. versionadded:: 0.0.6 """returnlist(self.xa_elem.arrayByApplyingSelector_("name"))
[docs]defcolor(self)->list[str]:"""Gets the color of each calendar in the list. :return: A list of calendar color strings
- :rtype: List[str]
+ :rtype: list[str] .. versionadded:: 0.0.6 """ls=self.xa_elem.arrayByApplyingSelector_("color")return[XABase.XAColor(x)forxinls]
[docs]defcalendar_identifier(self)->list[str]:"""Gets the ID of each calendar in the list. :return: A list of calendar IDs
- :rtype: List[str]
+ :rtype: list[str] .. versionadded:: 0.0.6 """returnlist(self.xa_elem.arrayByApplyingSelector_("calendarIdentifier"))
[docs]defwritable(self)->list[bool]:"""Gets the writable status of each calendar in the list. :return: A list of calendar writable status boolean values
- :rtype: List[bool]
+ :rtype: list[bool] .. versionadded:: 0.0.6 """returnlist(self.xa_elem.arrayByApplyingSelector_("writable"))
[docs]defdescription(self)->list[str]:"""Gets the description of each calendar in the list. :return: A list of calendar descriptions
- :rtype: List[str]
+ :rtype: list[str] .. versionadded:: 0.0.6 """
@@ -777,10 +798,18 @@
[docs]defproperties(self)->list[dict]:"""Gets the properties of each attendee in the list. :return: A list of attendee properties dictionaries
- :rtype: List[dict]
+ :rtype: list[dict] .. versionadded:: 0.0.6 """returnlist(self.xa_elem.arrayByApplyingSelector_("properties"))
[docs]defdisplay_name(self)->list[str]:"""Gets the display name of each attendee in the list. :return: A list of attendee first and last names
- :rtype: List[str]
+ :rtype: list[str] .. versionadded:: 0.0.6 """returnlist(self.xa_elem.arrayByApplyingSelector_("displayName"))
[docs]defemail(self)->list[str]:"""Gets the email address of each attendee in the list. :return: A list of attendee email addresses
- :rtype: List[str]
+ :rtype: list[str] .. versionadded:: 0.0.6 """returnlist(self.xa_elem.arrayByApplyingSelector_("email"))
[docs]defparticipation_status(self)->list[XACalendarApplication.ParticipationStatus]:"""Gets the participation status of each attendee in the list. :return: A list of attendee participation statuses
- :rtype: List[XACalendarApplication.ParticipationStatus]
+ :rtype: list[XACalendarApplication.ParticipationStatus] .. versionadded:: 0.0.6 """
@@ -1117,142 +1170,142 @@
Source code for PyXA.apps.Calendar
def__init__(self,properties:dict,filter:Union[dict,None]=None):super().__init__(properties,XACalendarEvent,filter)
- defproperties(self)->List[dict]:
+ defproperties(self)->list[dict]:"""Gets the properties of each event in the list. :return: A list of event properties dictionaries
- :rtype: List[dict]
+ :rtype: list[dict] .. versionadded:: 0.0.6 """returnlist(self.xa_elem.arrayByApplyingSelector_("properties"))
-
[docs]defdescription(self)->list[str]:"""Gets the description of each event in the list. :return: A list of event descriptions
- :rtype: List[str]
+ :rtype: list[str] .. versionadded:: 0.0.6 """returnlist(self.xa_elem.arrayByApplyingSelector_("description"))
[docs]defstart_date(self)->list[datetime]:"""Gets the start date of each event in the list. :return: A list of event start dates
- :rtype: List[datetime]
+ :rtype: list[datetime] .. versionadded:: 0.0.6 """returnlist(self.xa_elem.arrayByApplyingSelector_("startDate"))
[docs]defproperties(self)->list[datetime]:"""Gets the end date of each event in the list. :return: A list of event end dates
- :rtype: List[datetime]
+ :rtype: list[datetime] .. versionadded:: 0.0.6 """returnlist(self.xa_elem.arrayByApplyingSelector_("endDate"))
[docs]defallday_event(self)->list[bool]:"""Gets the all-day status of each event in the list. :return: A list of event all-day status boolean values
- :rtype: List[bool]
+ :rtype: list[bool] .. versionadded:: 0.0.6 """returnlist(self.xa_elem.arrayByApplyingSelector_("alldayEvent"))
[docs]defrecurrence(self)->list[str]:"""Gets the recurrence string of each event in the list. :return: A list of event recurrence strings
- :rtype: List[str]
+ :rtype: list[str] .. versionadded:: 0.0.6 """returnlist(self.xa_elem.arrayByApplyingSelector_("recurrence"))
[docs]defsequence(self)->list[int]:"""Gets the version of each event in the list. :return: A list of event versions
- :rtype: List[int]
+ :rtype: list[int] .. versionadded:: 0.0.6 """returnlist(self.xa_elem.arrayByApplyingSelector_("sequence"))
[docs]defstamp_date(self)->list[datetime]:"""Gets the modification date of each event in the list. :return: A list of event modification dates
- :rtype: List[datetime]
+ :rtype: list[datetime] .. versionadded:: 0.0.6 """returnlist(self.xa_elem.arrayByApplyingSelector_("stampDate"))
[docs]defexcluded_dates(self)->list[list[datetime]]:"""Gets the excluded dates of each event in the list. :return: A list of event excluded dates
- :rtype: List[List[datetime]]
+ :rtype: list[list[datetime]] .. versionadded:: 0.0.6 """returnlist(self.xa_elem.arrayByApplyingSelector_("excludedDates"))
[docs]defstatus(self)->list[XACalendarApplication.EventStatus]:"""Gets the status of each event in the list. :return: A list of event statuses
- :rtype: List[XACalendarApplication.EventStatus]
+ :rtype: list[XACalendarApplication.EventStatus] .. versionadded:: 0.0.6 """ls=self.xa_elem.arrayByApplyingSelector_("status")return[XACalendarApplication.EventStatus(XABase.OSType(x.stringValue()))forxinls]
[docs]defsummary(self)->list[str]:"""Gets the summary of each event in the list. :return: A list of event summaries
- :rtype: List[str]
+ :rtype: list[str] .. versionadded:: 0.0.6 """returnlist(self.xa_elem.arrayByApplyingSelector_("summary"))
[docs]deflocation(self)->list[str]:"""Gets the location string of each event in the list. :return: A list of event locations
- :rtype: List[str]
+ :rtype: list[str] .. versionadded:: 0.0.6 """returnlist(self.xa_elem.arrayByApplyingSelector_("location"))
[docs]defuid(self)->list[str]:"""Gets the unique identifier of each event in the list. :return: A list of event IDs
- :rtype: List[str]
+ :rtype: list[str] .. versionadded:: 0.0.6 """returnlist(self.xa_elem.arrayByApplyingSelector_("uid"))
[docs]defurl(self)->list[str]:"""Gets the URL associated to each event in the list. :return: A list of event URLs
- :rtype: List[str]
+ :rtype: list[str] .. versionadded:: 0.0.6 """
@@ -1338,7 +1391,7 @@
[docs]defby_excluded_dates(self,excluded_dates:list[datetime])->Union['XACalendarEvent',None]:"""Retrieves the first event whose excluded dates date matches the given list of dates, if one exists. :return: The desired event, if it is found
@@ -1419,7 +1472,7 @@
Source code for PyXA.apps.Calendar
self.recurrence:str#: A string describing the event recurrenceself.sequence:int#: The event versionself.stamp_date:date#: The date the event was last modified
- self.excluded_dates:List[datetime]#: The exception dates for the event
+ self.excluded_dates:list[datetime]#: The exception dates for the eventself.status:XACalendarApplication.EventStatus#: The status of the eventself.summary:str#: The summary (title) of the eventself.location:str#: The location of the event
@@ -1427,7 +1480,7 @@
Source code for PyXA.apps.Calendar
self.url:str#: The URL associated with the eventifhasattr(self.xa_elem,"uid"):
- events=NSMutableArray.arrayWithArray_([])
+ events=AppKit.NSMutableArray.arrayWithArray_([])foryearinrange(2006,datetime.now().year+4,4):start_date=date(year,1,1)end_date=start_date+timedelta(days=365*4)
@@ -1443,22 +1496,42 @@
[docs]deftype(self)->list[str]:"""Gets the type of each attachment in the list. :return: A list of attachment types
- :rtype: List[str]
+ :rtype: list[str] .. versionadded:: 0.0.6 """returnlist(self.xa_elem.arrayByApplyingSelector_("type"))
[docs]deffile_name(self)->list[str]:"""Gets the file name of each attachment in the list. :return: A list of attachment file names
- :rtype: List[str]
+ :rtype: list[str] .. versionadded:: 0.0.6 """returnlist(self.xa_elem.arrayByApplyingSelector_("filename"))
[docs]deffile(self)->list[XABase.XAPath]:"""Gets the file path of each attachment in the list. :return: A list of attachment file paths
- :rtype: List[XABase.XAPath]
+ :rtype: list[XABase.XAPath] .. versionadded:: 0.0.6 """ls=self.xa_elem.arrayByApplyingSelector_("file")return[XABase.XAPath(x)forxinls]
[docs]defurl(self)->list[XABase.XAURL]:"""Gets the URL of each attachment in the list. :return: A list of attachment file URLs
- :rtype: List[XABase.XAURL]
+ :rtype: list[XABase.XAURL] .. versionadded:: 0.0.6 """ls=self.xa_elem.arrayByApplyingSelector_("URL")return[XABase.XAURL(x)forxinls]
[docs]classXACardhopAppplication(XABaseScriptable.XASBApplication,XACanOpenPath,XACanPrintPath):
+ """A class for interacting with Cardhop.app.
+
+ .. versionadded:: 0.1.0
+ """
+
[docs]classZoomType(Enum):
+ """Options for zoom type to use when opening a new document.
+ """
+ NO_VARY=0
+ FIT_PAGE=1
+ FIT_WIDTH=2
+ FIT_HEIGHT=3
+ FIT_VISIBLE_WIDTH=4
+
+ def__init__(self,properties):
+ super().__init__(properties)
+ self.xa_wcls=XACardhopWindow
+
+ self.name:str#: The name of the application
+ self.frontmost:bool#: Whether Cardhop is the active application
+ self.version:str#: The version of Cardhop.app
+
+
[docs]defparse_sentence(self,sentence:str,add_immediately:bool=True):
+ """Parses the given sentence and carries out the corresponding actions.
+
+ :param sentence: The sentence to parse
+ :type sentence: str
+ :param add_immediately: Whether to immediately parse the sentence and save resulting changes, instead of having the user confirm changes via the GUI, defaults to True
+ :type add_immediately: bool, optional
+ """
+ self.xa_scel.parseSentence_addImmediately_(sentence,add_immediately)
+
+
[docs]defdocuments(self,filter:dict=None)->'XACardhopDocumentList':
+ """Returns a list of documents, as PyXA objects, matching the filter.
+
+ :param filter: A dictionary specifying property-value pairs that all returned documents will have
+ :type filter: dict
+ :return: The list of documents
+ :rtype: XACardhopDocumentList
+
+ .. versionadded:: 0.1.0
+ """
+ returnself._new_element(self.xa_scel.documents(),XACardhopDocumentList,filter)
+
+
+
+
+
[docs]classXACardhopWindow(XABaseScriptable.XASBWindow,XAPrintable):
+ """A window of Cardhop.app.
+
+ .. versionadded:: 0.1.0
+ """
+ def__init__(self,properties):
+ super().__init__(properties)
+
+ self.name:str#: The title of the window
+ self.id:int#: The unique identifier of the window
+ self.index:int#: The index of the window, ordered front to back
+ self.bounds:Tuple[int,int,int,int]#: The bounding rectangle of the window
+ self.closeable:bool#: Whether the window has a close button
+ self.miniaturizable:bool#: Whether the window has a minimize button
+ self.miniaturized:bool#: Whether the window is currently minimized
+ self.resizable:bool#: Whether the window can be resized
+ self.visible:bool#: Whether the window is currently visible
+ self.zoomable:bool#: Whether the window has a zoom button
+ self.zoomed:bool#;; Whether the window is currently zoomed
+ self.document:XACardhopDocument#: The document whose contents are displayed in the window
+
+ @property
+ defname(self)->str:
+ returnself.xa_elem.name()
+
+ @property
+ defid(self)->int:
+ returnself.xa_elem.id()
+
+ @property
+ defindex(self)->int:
+ returnself.xa_elem.index()
+
+ @index.setter
+ defindex(self,index:int):
+ self.set_property('index',index)
+
+ @property
+ defbounds(self)->Tuple[int,int,int,int]:
+ rect=self.xa_elem.bounds()
+ origin=rect.origin
+ size=rect.size
+ return(origin.x,origin.y,size.width,size.height)
+
+ @bounds.setter
+ defbounds(self,bounds:Tuple[int,int,int,int]):
+ x=bounds[0]
+ y=bounds[1]
+ w=bounds[2]
+ h=bounds[3]
+ value=AppKit.NSValue.valueWithRect_(AppKit.NSMakeRect(x,y,w,h))
+ self.set_property("bounds",value)
+
+ @property
+ defcloseable(self)->bool:
+ returnself.xa_elem.closeable()
+
+ @property
+ defminiaturizable(self)->bool:
+ returnself.xa_elem.miniaturizable()
+
+ @property
+ defminiaturized(self)->bool:
+ returnself.xa_elem.miniaturized()
+
+ @miniaturized.setter
+ defminiaturized(self,miniaturized:bool):
+ self.set_property('miniaturized',miniaturized)
+
+ @property
+ defresizable(self)->bool:
+ returnself.xa_elem.resizable()
+
+ @property
+ defvisible(self)->bool:
+ returnself.xa_elem.visible()
+
+ @visible.setter
+ defvisible(self,visible:bool):
+ self.set_property('visible',visible)
+
+ @property
+ defzoomable(self)->bool:
+ returnself.xa_elem.zoomable()
+
+ @property
+ defzoomed(self)->bool:
+ returnself.xa_elem.zoomed()
+
+ @zoomed.setter
+ defzoomed(self,zoomed:bool):
+ self.set_property('zoomed',zoomed)
+
+ @property
+ defdocument(self)->'XACardhopDocument':
+ returnself._new_element(self.xa_elem.document(),XACardhopDocument)
+
+
+
+
+
[docs]classXACardhopDocumentList(XABase.XAList,XAPrintable,XAClipboardCodable):
+ """A wrapper around lists 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.
+
+ .. versionadded:: 0.1.0
+ """
+ def__init__(self,properties:dict,filter:Union[dict,None]=None):
+ super().__init__(properties,XACardhopDocument,filter)
+
+
[docs]defname(self)->List[str]:
+ """Gets the name of each document in the list.
+
+ :return: A list of document names
+ :rtype: List[str]
+
+ .. versionadded:: 0.1.0
+ """
+ returnlist(self.xa_elem.arrayByApplyingSelector_("name"))
+
+
[docs]defmodified(self)->List[bool]:
+ """Gets the modified status of each document in the list.
+
+ :return: A list of document modified status booleans
+ :rtype: List[bool]
+
+ .. versionadded:: 0.1.0
+ """
+ returnlist(self.xa_elem.arrayByApplyingSelector_("modified"))
+
+
[docs]deffile(self)->List[XABase.XAPath]:
+ """Gets the file path of each document in the list.
+
+ :return: A list of document file paths
+ :rtype: List[XABase.XAPath]
+
+ .. versionadded:: 0.1.0
+ """
+ ls=self.xa_elem.arrayByApplyingSelector_("file")
+ return[XABase.XAPath(x)forxinls]
+
+
[docs]defby_name(self,name:str)->Union['XACardhopDocument',None]:
+ """Retrieves the first document whose name matches the given name, if one exists.
+
+ :return: The desired document, if it is found
+ :rtype: Union[XACardhopDocument, None]
+
+ .. versionadded:: 0.1.0
+ """
+ returnself.by_property("name",name)
+
+
[docs]defby_modified(self,modified:bool)->Union['XACardhopDocument',None]:
+ """Retrieves the first document whose modified status matches the given boolean value, if one exists.
+
+ :return: The desired document, if it is found
+ :rtype: Union[XACardhopDocument, None]
+
+ .. versionadded:: 0.1.0
+ """
+ returnself.by_property("modified",modified)
+
+
[docs]defby_file(self,file:Union[XABase.XAPath,str])->Union['XACardhopDocument',None]:
+ """Retrieves the first document whose file path matches the given path, if one exists.
+
+ :return: The desired document, if it is found
+ :rtype: Union[XACardhopDocument, None]
+
+ .. versionadded:: 0.1.0
+ """
+ ifisinstance(file,str):
+ file=XABase.XAPath(file)
+ returnself.by_property("file",file.xa_elem)
+
+
[docs]defget_clipboard_representation(self)->List[Union[str,AppKit.NSURL]]:
+ """Gets a clipboard-codable representation of each document in the list.
+
+ When the clipboard content is set to a list of documents, each documents's file URL and name are added to the clipboard.
+
+ :return: A list of each document's file URL and name
+ :rtype: List[Union[str, AppKit.NSURL]]
+
+ .. versionadded:: 0.0.8
+ """
+ items=[]
+ names=self.name()
+ paths=self.file()
+ forindex,textinenumerate(names):
+ items.append(str(text),paths[index].xa_elem)
+ returnitems
[docs]classXACardhopDocument(XABase.XAObject):
+ """A document of Cardhop.app.
+
+ .. versionadded:: 0.1.0
+ """
+ def__init__(self,properties):
+ super().__init__(properties)
+
+ self.name:str#: The title of the document
+ self.modified:bool#: Whether the document has been modified since its last save
+ self.file:XABase.XAPath#: The location of the document on disk, if it has one
+
+ @property
+ defname(self)->str:
+ returnself.xa_elem.name()
+
+ @property
+ defmodified(self)->bool:
+ returnself.xa_elem.modified()
+
+ @property
+ deffile(self)->XABase.XAPath:
+ returnXABase.XAPath(self.xa_elem.file())
+
+
+
+
+
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/docs/_modules/PyXA/apps/Cardhop.html b/docs/_modules/PyXA/apps/Cardhop.html
new file mode 100644
index 0000000..2a90d06
--- /dev/null
+++ b/docs/_modules/PyXA/apps/Cardhop.html
@@ -0,0 +1,380 @@
+
+
+
+
+
+ PyXA.apps.Cardhop — PyXA 0.1.0 documentation
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
[docs]classXACardhopAppplication(XABaseScriptable.XASBApplication,XACanOpenPath,XACanPrintPath):
+ """A class for interacting with Cardhop.app.
+
+ .. versionadded:: 0.1.0
+ """
+
[docs]classZoomType(Enum):
+ """Options for zoom type to use when opening a new document.
+ """
+ NO_VARY=0
+ FIT_PAGE=1
+ FIT_WIDTH=2
+ FIT_HEIGHT=3
+ FIT_VISIBLE_WIDTH=4
+
+ def__init__(self,properties):
+ super().__init__(properties)
+ self.xa_wcls=XACardhopWindow
+
+ self.name:str#: The name of the application
+ self.frontmost:bool#: Whether Cardhop is the active application
+ self.version:str#: The version of Cardhop.app
+
+
[docs]defparse_sentence(self,sentence:str,add_immediately:bool=True):
+ """Parses the given sentence and carries out the corresponding actions.
+
+ :param sentence: The sentence to parse
+ :type sentence: str
+ :param add_immediately: Whether to immediately parse the sentence and save resulting changes, instead of having the user confirm changes via the GUI, defaults to True
+ :type add_immediately: bool, optional
+ """
+ self.xa_scel.parseSentence_addImmediately_(sentence,add_immediately)
+
+
[docs]defdocuments(self,filter:dict=None)->'XACardhopDocumentList':
+ """Returns a list of documents, as PyXA objects, matching the filter.
+
+ :param filter: A dictionary specifying property-value pairs that all returned documents will have
+ :type filter: dict
+ :return: The list of documents
+ :rtype: XACardhopDocumentList
+
+ .. versionadded:: 0.1.0
+ """
+ returnself._new_element(self.xa_scel.documents(),XACardhopDocumentList,filter)
+
+
+
+
+
[docs]classXACardhopWindow(XABaseScriptable.XASBWindow,XAPrintable):
+ """A window of Cardhop.app.
+
+ .. versionadded:: 0.1.0
+ """
+ def__init__(self,properties):
+ super().__init__(properties)
+
+ self.name:str#: The title of the window
+ self.id:int#: The unique identifier of the window
+ self.index:int#: The index of the window, ordered front to back
+ self.bounds:tuple[int,int,int,int]#: The bounding rectangle of the window
+ self.closeable:bool#: Whether the window has a close button
+ self.miniaturizable:bool#: Whether the window has a minimize button
+ self.miniaturized:bool#: Whether the window is currently minimized
+ self.resizable:bool#: Whether the window can be resized
+ self.visible:bool#: Whether the window is currently visible
+ self.zoomable:bool#: Whether the window has a zoom button
+ self.zoomed:bool#;; Whether the window is currently zoomed
+ self.document:XACardhopDocument#: The document whose contents are displayed in the window
+
+ @property
+ defname(self)->str:
+ returnself.xa_elem.name()
+
+ @property
+ defid(self)->int:
+ returnself.xa_elem.id()
+
+ @property
+ defindex(self)->int:
+ returnself.xa_elem.index()
+
+ @index.setter
+ defindex(self,index:int):
+ self.set_property('index',index)
+
+ @property
+ defbounds(self)->tuple[int,int,int,int]:
+ rect=self.xa_elem.bounds()
+ origin=rect.origin
+ size=rect.size
+ return(origin.x,origin.y,size.width,size.height)
+
+ @bounds.setter
+ defbounds(self,bounds:tuple[int,int,int,int]):
+ x=bounds[0]
+ y=bounds[1]
+ w=bounds[2]
+ h=bounds[3]
+ value=AppKit.NSValue.valueWithRect_(AppKit.NSMakeRect(x,y,w,h))
+ self.set_property("bounds",value)
+
+ @property
+ defcloseable(self)->bool:
+ returnself.xa_elem.closeable()
+
+ @property
+ defminiaturizable(self)->bool:
+ returnself.xa_elem.miniaturizable()
+
+ @property
+ defminiaturized(self)->bool:
+ returnself.xa_elem.miniaturized()
+
+ @miniaturized.setter
+ defminiaturized(self,miniaturized:bool):
+ self.set_property('miniaturized',miniaturized)
+
+ @property
+ defresizable(self)->bool:
+ returnself.xa_elem.resizable()
+
+ @property
+ defvisible(self)->bool:
+ returnself.xa_elem.visible()
+
+ @visible.setter
+ defvisible(self,visible:bool):
+ self.set_property('visible',visible)
+
+ @property
+ defzoomable(self)->bool:
+ returnself.xa_elem.zoomable()
+
+ @property
+ defzoomed(self)->bool:
+ returnself.xa_elem.zoomed()
+
+ @zoomed.setter
+ defzoomed(self,zoomed:bool):
+ self.set_property('zoomed',zoomed)
+
+ @property
+ defdocument(self)->'XACardhopDocument':
+ returnself._new_element(self.xa_elem.document(),XACardhopDocument)
+
+
+
+
+
[docs]classXACardhopDocumentList(XABase.XAList,XAPrintable,XAClipboardCodable):
+ """A wrapper around lists 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.
+
+ .. versionadded:: 0.1.0
+ """
+ def__init__(self,properties:dict,filter:Union[dict,None]=None):
+ super().__init__(properties,XACardhopDocument,filter)
+
+
[docs]defname(self)->list[str]:
+ """Gets the name of each document in the list.
+
+ :return: A list of document names
+ :rtype: list[str]
+
+ .. versionadded:: 0.1.0
+ """
+ returnlist(self.xa_elem.arrayByApplyingSelector_("name"))
+
+
[docs]defmodified(self)->list[bool]:
+ """Gets the modified status of each document in the list.
+
+ :return: A list of document modified status booleans
+ :rtype: list[bool]
+
+ .. versionadded:: 0.1.0
+ """
+ returnlist(self.xa_elem.arrayByApplyingSelector_("modified"))
+
+
[docs]deffile(self)->list[XABase.XAPath]:
+ """Gets the file path of each document in the list.
+
+ :return: A list of document file paths
+ :rtype: list[XABase.XAPath]
+
+ .. versionadded:: 0.1.0
+ """
+ ls=self.xa_elem.arrayByApplyingSelector_("file")
+ return[XABase.XAPath(x)forxinls]
+
+
[docs]defby_name(self,name:str)->Union['XACardhopDocument',None]:
+ """Retrieves the first document whose name matches the given name, if one exists.
+
+ :return: The desired document, if it is found
+ :rtype: Union[XACardhopDocument, None]
+
+ .. versionadded:: 0.1.0
+ """
+ returnself.by_property("name",name)
+
+
[docs]defby_modified(self,modified:bool)->Union['XACardhopDocument',None]:
+ """Retrieves the first document whose modified status matches the given boolean value, if one exists.
+
+ :return: The desired document, if it is found
+ :rtype: Union[XACardhopDocument, None]
+
+ .. versionadded:: 0.1.0
+ """
+ returnself.by_property("modified",modified)
+
+
[docs]defby_file(self,file:Union[XABase.XAPath,str])->Union['XACardhopDocument',None]:
+ """Retrieves the first document whose file path matches the given path, if one exists.
+
+ :return: The desired document, if it is found
+ :rtype: Union[XACardhopDocument, None]
+
+ .. versionadded:: 0.1.0
+ """
+ ifisinstance(file,str):
+ file=XABase.XAPath(file)
+ returnself.by_property("file",file.xa_elem)
+
+
[docs]defget_clipboard_representation(self)->list[Union[str,AppKit.NSURL]]:
+ """Gets a clipboard-codable representation of each document in the list.
+
+ When the clipboard content is set to a list of documents, each documents's file URL and name are added to the clipboard.
+
+ :return: A list of each document's file URL and name
+ :rtype: list[Union[str, AppKit.NSURL]]
+
+ .. versionadded:: 0.0.8
+ """
+ items=[]
+ names=self.name()
+ paths=self.file()
+ forindex,textinenumerate(names):
+ items.append(str(text),paths[index].xa_elem)
+ returnitems
[docs]classXACardhopDocument(XABase.XAObject):
+ """A document of Cardhop.app.
+
+ .. versionadded:: 0.1.0
+ """
+ def__init__(self,properties):
+ super().__init__(properties)
+
+ self.name:str#: The title of the document
+ self.modified:bool#: Whether the document has been modified since its last save
+ self.file:XABase.XAPath#: The location of the document on disk, if it has one
+
+ @property
+ defname(self)->str:
+ returnself.xa_elem.name()
+
+ @property
+ defmodified(self)->bool:
+ returnself.xa_elem.modified()
+
+ @property
+ deffile(self)->XABase.XAPath:
+ returnXABase.XAPath(self.xa_elem.file())
[docs]classXAChromiumApplication(XABaseScriptable.XASBApplication,XACanOpenPath):
+ """A class for managing and interacting with Chromium.app.
+
+ .. seealso:: :class:`XAChromiumWindow`, :class:`XAChromiumBookmarkFolder`, :class:`XAChromiumBookmarkItem`, :class:`XAChromiumTab`
+
+ .. versionadded:: 0.0.3
+ """
+ def__init__(self,properties):
+ super().__init__(properties)
+ self.xa_wcls=XAChromiumWindow
+
+ self.name:str#: The name of the application
+ self.frontmost:bool#: Whether Chromium is the active application
+ self.version:str#: The version of Chromium
+ self.bookmarks_bar:XAChromiumBookmarkFolder#: The bookmarks bar bookmark folder
+ self.other_bookmarks:XAChromiumBookmarkFolder#: The other bookmarks bookmark folder
+
+ @property
+ defname(self)->str:
+ returnself.xa_scel.name()
+
+ @property
+ deffrontmost(self)->bool:
+ returnself.xa_scel.frontmost()
+
+ @frontmost.setter
+ deffrontmost(self,frontmost:bool):
+ self.set_property("frontmost",frontmost)
+
+ @property
+ defversion(self)->str:
+ returnself.xa_scel.version()
+
+ @property
+ defbookmarks_bar(self)->'XAChromiumBookmarkFolder':
+ returnself._new_element(self.xa_scel.bookmarksBar(),XAChromiumBookmarkFolder)
+
+ @property
+ defother_bookmarks(self)->'XAChromiumBookmarkFolder':
+ returnself._new_element(self.xa_scel.otherBookmarks(),XAChromiumBookmarkFolder)
+
+
[docs]defopen(self,url:Union[str,XABase.XAURL]="https://google.com")->'XAChromiumApplication':
+ """Opens a URL in a new tab.
+
+ :param url: _description_, defaults to "http://google.com"
+ :type url: str, optional
+ :return: A reference to the Chromium application object.
+ :rtype: XAChromiumApplication
+
+ :Example 1: Open a local or external URL
+
+ >>> import PyXA
+ >>> app = PyXA.application("Chromium")
+ >>> app.open("https://www.google.com")
+ >>> app.open("google.com")
+ >>> app.open("/Users/exampleuser/Documents/WebPage.html")
+
+ .. versionadded:: 0.0.3
+ """
+ ifisinstance(url,str):
+ ifurl.startswith("/"):
+ # URL is a path to file
+ self.xa_wksp.openFile_application_(url,self.xa_scel)
+ returnself
+ # Otherwise, URL is web address
+ elifnoturl.startswith("http"):
+ url="http://"+url
+ url=XABase.XAURL(url)
+ self.xa_wksp.openURLs_withAppBundleIdentifier_options_additionalEventParamDescriptor_launchIdentifiers_([url.xa_elem],self.xa_elem.bundleIdentifier(),0,None,None)
+ returnself
+
+
[docs]defbookmark_folders(self,filter:Union[dict,None]=None)->'XAChromiumBookmarkFolderList':
+ """Returns a list of bookmark folders, as PyXA objects, matching the given filter.
+
+ :param filter: Keys and values to filter folders by, defaults to None
+ :type filter: dict, optional
+ :return: A PyXA list object wrapping a list of bookmark folders
+ :rtype: XAChromiumBookmarkFolderList
+
+ .. versionadded:: 0.0.3
+ """
+ returnself._new_element(self.xa_scel.bookmarkFolders(),XAChromiumBookmarkFolderList,filter)
+
+
[docs]defnew_window(self,url:Union[str,XABase.XAURL,None]=None)->'XAChromiumWindow':
+ """Opens a new window at the specified URL.
+
+
+ :param url: The URL to open in a new window, or None to open the window at the homepage, defaults to None
+ :type url: Union[str, XABase.XAURL, None], optional
+ :return: The newly created window object
+ :rtype: XAChromiumWindow
+
+ .. seealso:: :func:`new_tab`, :func:`make`
+
+ .. versionadded:: 0.0.5
+ """
+ new_window=self.make("window")
+ self.windows().push(new_window)
+
+ ifisinstance(url,str):
+ ifurl.startswith("/"):
+ # URL is a path to file
+ self.xa_wksp.openFile_application_(url,self.xa_scel)
+ returnself
+ # Otherwise, URL is web address
+ elifnoturl.startswith("http"):
+ url="http://"+url
+ url=XABase.XAURL(url)
+ new_window.active_tab.set_property("URL",url.xa_elem)
+ returnnew_window
+
+
[docs]defnew_tab(self,url:Union[str,XABase.XAURL,None]=None)->'XAChromiumTab':
+ """Opens a new tab at the specified URL.
+
+ :param url: The URL to open in a new tab, or None to open the tab at the homepage, defaults to None
+ :type url: Union[str, XABase.XAURL, None], optional
+ :return: The newly created tab object
+ :rtype: XAChromiumTab
+
+ .. seealso:: :func:`new_window`, :func:`make`
+
+ .. versionadded:: 0.0.5
+ """
+ new_tab=None
+ ifurlisNone:
+ new_tab=self.make("tab")
+ else:
+ new_tab=self.make("tab",{"URL":url})
+ self.front_window.tabs().push(new_tab)
+ returnnew_tab
+
+
[docs]defmake(self,specifier:str,properties:dict=None):
+ """Creates a new element of the given specifier class without adding it to any list.
+
+ Use :func:`XABase.XAList.push` to push the element onto a list.
+
+ :param specifier: The classname of the object to create
+ :type specifier: str
+ :param properties: The properties to give the object
+ :type properties: dict
+ :return: A PyXA wrapped form of the object
+ :rtype: XABase.XAObject
+
+ .. seealso:: :func:`new_window`, :func:`new_tab`
+
+ .. versionadded:: 0.0.4
+ """
+ ifpropertiesisNone:
+ properties={}
+
+ obj=self.xa_scel.classForScriptingClass_(specifier).alloc().initWithProperties_(properties)
+
+ ifspecifier=="tab":
+ returnself._new_element(obj,XAChromiumTab)
+ elifspecifier=="window":
+ returnself._new_element(obj,XAChromiumWindow)
+
+
+
+
+
[docs]classXAChromiumWindow(XABaseScriptable.XASBWindow):
+ """A class for managing and interacting with Chromium windows.
+
+ .. seealso:: :class:`XAChromiumApplication`, :class:`XAChromiumTab`
+
+ .. versionadded:: 0.0.3
+ """
+ def__init__(self,properties):
+ super().__init__(properties)
+ self.given_name:str#: The given name of the window
+ self.name:str#: The full title of the window
+ self.id:int#: The unique identifier for the window
+ self.index:int#: The index of the window in the front-to-back ordering
+ self.bounds:Tuple[int,int,int,int]#: The bounding rectangle of the window
+ self.closeable:bool#: Whether the window has a close button
+ self.minimizable:bool#: Whether the window can be minimized
+ self.minimized:bool#: Whether the window is currently minimized
+ self.resizable:bool#: Whether the window can be resized
+ self.visible:bool#: Whether the window is currently visible
+ self.zoomable:bool#: Whether the window can be zoomed
+ self.zoomed:bool#: Whether the window is currently zoomed
+ self.mode:str#: The mode of the window, either "normal" or "incognito"
+ self.active_tab_index:int#: The index of the active tab
+ self.active_tab:XAChromiumTab#: The currently selected tab
+
+ @property
+ defgiven_name(self)->str:
+ returnself.xa_elem.givenName()
+
+ @given_name.setter
+ defgiven_name(self,given_name:str):
+ self.set_property("givenName",given_name)
+
+ @property
+ defname(self)->str:
+ returnself.xa_elem.name()
+
+ @property
+ defid(self)->int:
+ returnself.xa_elem.id()
+
+ @property
+ defindex(self)->int:
+ returnself.xa_elem.index()
+
+ @index.setter
+ defindex(self,index:int):
+ self.set_property("index",index)
+
+ @property
+ defbounds(self)->Tuple[int,int,int,int]:
+ rect=self.xa_elem.bounds()
+ origin=rect.origin
+ size=rect.size
+ return(origin.x,origin.y,size.width,size.height)
+
+ @bounds.setter
+ defbounds(self,bounds:Tuple[int,int,int,int]):
+ x=bounds[0]
+ y=bounds[1]
+ w=bounds[2]
+ h=bounds[3]
+ value=AppKit.NSValue.valueWithRect_(AppKit.NSMakeRect(x,y,w,h))
+ self.set_property("bounds",value)
+
+ @property
+ defcloseable(self)->bool:
+ returnself.xa_elem.closeable()
+
+ @property
+ defminimizable(self)->bool:
+ returnself.xa_elem.minimizable()
+
+ @property
+ defminimized(self)->bool:
+ returnself.xa_elem.minimized()
+
+ @minimized.setter
+ defminimized(self,minimized:bool):
+ self.set_property("minimized",minimized)
+
+ @property
+ defresizable(self)->bool:
+ returnself.xa_elem.resizable()
+
+ @property
+ defvisible(self)->bool:
+ returnself.xa_elem.visible()
+
+ @visible.setter
+ defvisible(self,visible:bool):
+ self.set_property("visible",visible)
+
+ @property
+ defzoomable(self)->bool:
+ returnself.xa_elem.zoomable()
+
+ @property
+ defzoomed(self)->bool:
+ returnself.xa_elem.zoomed()
+
+ @zoomed.setter
+ defzoomed(self,zoomed:bool):
+ self.set_property("zoomed",zoomed)
+
+ @property
+ defmode(self)->str:
+ returnself.xa_elem.mode()
+
+ @mode.setter
+ defmode(self,mode:str):
+ self.set_property("mode",mode)
+
+ @property
+ defactive_tab_index(self)->int:
+ returnself.xa_elem.activeTabIndex()
+
+ @active_tab_index.setter
+ defactive_tab_index(self,active_tab_index:int):
+ self.set_property("activeTabIndex",active_tab_index)
+
+ @property
+ defactive_tab(self)->'XAChromiumTab':
+ returnself._new_element(self.xa_elem.activeTab(),XAChromiumTab)
+
+ @active_tab.setter
+ defactive_tab(self,active_tab:'XAChromiumTab'):
+ self.set_property("activeTab",active_tab.xa_elem)
+
+
[docs]defnew_tab(self,url:Union[str,XABase.XAURL,None]=None)->'XAChromiumTab':
+ """Opens a new tab at the specified URL.
+
+ :param url: The URL to open in a new tab, or None to open the tab at the homepage, defaults to None
+ :type url: Union[str, XABase.XAURL, None], optional
+ :return: The newly created tab object
+ :rtype: XAChromiumTab
+
+ .. versionadded:: 0.0.5
+ """
+ new_tab=None
+ ifurlisNone:
+ new_tab=self.xa_prnt.xa_prnt.make("tab")
+ else:
+ new_tab=self.xa_prnt.xa_prnt.make("tab",{"URL":url})
+ self.tabs().push(new_tab)
+ returnnew_tab
+
+
[docs]deftabs(self,filter:Union[dict,None]=None)->'XAChromiumTabList':
+ """Returns a list of tabs, as PyXA objects, matching the given filter.
+
+ :param filter: Keys and values to filter tabs by, defaults to None
+ :type filter: dict, optional
+ :return: A PyXA list object wrapping a list of tabs
+ :rtype: XAChromiumTabList
+
+ .. versionadded:: 0.0.3
+ """
+ returnself._new_element(self.xa_elem.tabs(),XAChromiumTabList,filter)
+
+
+
+
+
[docs]classXAChromiumTabList(XABase.XAList,XAClipboardCodable):
+ """A wrapper around a list of tabs.
+
+ .. seealso:: :class:`XAChromiumTab`
+
+ .. versionadded:: 0.0.3
+ """
+ def__init__(self,properties:dict,filter:Union[dict,None]=None):
+ super().__init__(properties,XAChromiumTab,filter)
+
+
[docs]defid(self)->List[int]:
+ """Gets the ID of each tab in the list.
+
+ :return: A list of tab IDs
+ :rtype: List[int]
+
+ .. versionadded:: 0.0.4
+ """
+ returnlist(self.xa_elem.arrayByApplyingSelector_("id"))
+
+
[docs]deftitle(self)->List[str]:
+ """Gets the title of each tab in the list.
+
+ :return: A list of tab titles
+ :rtype: List[str]
+
+ .. versionadded:: 0.0.4
+ """
+ returnlist(self.xa_elem.arrayByApplyingSelector_("title"))
+
+
[docs]defurl(self)->List[XABase.XAURL]:
+ """Gets the URL of each tab in the list.
+
+ :return: A list of tab URLS
+ :rtype: List[XABase.XAURL]
+
+ .. versionadded:: 0.0.4
+ """
+ ls=self.xa_elem.arrayByApplyingSelector_("URL")
+ return[XABase.XAURL(x)forxinls]
+
+
[docs]defloading(self)->List[bool]:
+ """Gets the loading state of each tab in the list.
+
+ :return: A list of loading states; a list of booleans.
+ :rtype: List[bool]
+
+ .. versionadded:: 0.0.4
+ """
+ returnlist(self.xa_elem.arrayByApplyingSelector_("loading"))
+
+
[docs]defby_id(self,id:int)->Union['XAChromiumTab',None]:
+ """Retrieves the tab whose ID matches the given ID, if one exists.
+
+ :return: The desired tab, if it is found
+ :rtype: Union[XAChromiumTab, None]
+
+ .. versionadded:: 0.0.4
+ """
+ returnself.by_property("id",id)
+
+
[docs]defby_title(self,title:str)->Union['XAChromiumTab',None]:
+ """Retrieves the first tab whose title matches the given title, if one exists.
+
+ :return: The desired tab, if it is found
+ :rtype: Union[XAChromiumTab, None]
+
+ .. versionadded:: 0.0.4
+ """
+ returnself.by_property("title",title)
+
+
[docs]defby_url(self,url:XABase.XAURL)->Union['XAChromiumTab',None]:
+ """Retrieves the first tab whose URL matches the given URL, if one exists.
+
+ :return: The desired tab, if it is found
+ :rtype: Union[XAChromiumTab, None]
+
+ .. versionadded:: 0.0.4
+ """
+ returnself.by_property("url",str(url.xa_elem))
+
+
[docs]defby_loading(self,loading:bool)->Union['XAChromiumTab',None]:
+ """Retrieves the first tab whose loading state matches the given boolean value, if one exists.
+
+ :return: The desired tab, if it is found
+ :rtype: Union[XAChromiumTab, None]
+
+ .. versionadded:: 0.0.4
+ """
+ returnself.by_property("loading",loading)
+
+
[docs]defget_clipboard_representation(self)->List[Union[str,AppKit.NSURL]]:
+ """Gets a clipboard-codable representation of each tab in the list.
+
+ When the clipboard content is set to a list of Chromium tabs, each tab's URL is added to the clipboard.
+
+ :return: A list of tab URLs
+ :rtype: List[Union[str, AppKit.NSURL]]
+
+ .. versionadded:: 0.0.8
+ """
+ items=[]
+ titles=self.title()
+ urls=self.url()
+ forindex,titleinenumerate(titles):
+ items.append(title)
+ items.append(urls[index].xa_elem)
+ returnitems
[docs]defundo(self)->'XAChromiumTab':
+ """Undoes the last action done on the tab.
+
+ .. versionadded:: 0.0.4
+ """
+ self.xa_elem.undo()
+ returnself
+
+
[docs]defredo(self)->'XAChromiumTab':
+ """Redoes the last action done on the tab.
+
+ .. versionadded:: 0.0.4
+ """
+ self.xa_elem.redo()
+ returnself
+
+
[docs]defcut_selection(self)->'XAChromiumTab':
+ """Attempts to cut the selected content and copy it to the clipboard. If the content cannot be deleted, then it is only copied to the clipboard.
+
+ .. versionadded:: 0.0.4
+ """
+ self.xa_elem.cutSelection()
+ returnself
+
+
[docs]defcopy_selection(self)->'XAChromiumTab':
+ """Copies the selected element to the clipboard.
+
+ .. versionadded:: 0.0.4
+ """
+ self.xa_elem.copySelection()
+ returnself
+
+
[docs]defpaste_selection(self)->'XAChromiumTab':
+ """Attempts to paste the clipboard into the selected element.
+
+ .. versionadded:: 0.0.4
+ """
+ self.xa_elem.pasteSelection()
+ returnself
+
+
[docs]defselect_all(self)->'XAChromiumTab':
+ """Selects all text content within the tab.
+
+ .. versionadded:: 0.0.4
+ """
+ self.xa_elem.selectAll()
+ returnself
+
+
[docs]defgo_back(self)->'XAChromiumTab':
+ """Goes to the previous URL in the tab's history.
+
+ .. versionadded:: 0.0.4
+ """
+ self.xa_elem.goBack()
+ returnself
+
+
[docs]defgo_forward(self)->'XAChromiumTab':
+ """Goes to the next URL in the tab's history, or does nothing if the current document is the most recent URL.
+
+ .. versionadded:: 0.0.4
+ """
+ self.xa_elem.goForward()
+ returnself
[docs]defstop(self)->'XAChromiumTab':
+ """Forces the tab to stop loading.
+
+ .. versionadded:: 0.0.4
+ """
+ self.xa_elem.stop()
+ returnself
+
+
[docs]defprint(self)->'XAChromiumTab':
+ """Opens the print dialog for the tab.
+
+ .. versionadded:: 0.0.4
+ """
+ self.xa_elem.print()
+ returnself
+
+
[docs]defview_source(self)->'XAChromiumTab':
+ """Opens the source HTML of the tab's document in a separate tab.
+
+ .. versionadded:: 0.0.4
+ """
+ self.xa_elem.viewSource()
+ returnself
[docs]defexecute(self,script:str)->Any:
+ """Executes JavaScript in the tab.
+
+ .. versionadded:: 0.0.4
+ """
+ returnself.xa_elem.executeJavascript_(script)
+
+
[docs]defmove_to(self,window:'XAChromiumWindow')->'XAChromiumWindow':
+ """Moves the tab to the specified window. After, the tab will exist in only one location.
+
+ :param window: The window to move the tab to.
+ :type window: XASafariWindow
+ :return: A reference to the tab object.
+ :rtype: XASafariGeneric
+
+ :Example 1: Move the current tab to the second window
+
+ >>> import PyXA
+ >>> app = PyXA.application("Chromium")
+ >>> tab = app.front_window.active_tab
+ >>> window2 = app.window(1)
+ >>> tab.move_to(window2)
+
+ .. seealso:: :func:`duplicate_to`
+
+ .. versionadded:: 0.0.1
+ """
+ current=self.xa_elem.get()
+ properties={"URL":self.url}
+ ifisinstance(self.xa_prnt,XABase.XAList):
+ new_tab=self.xa_prnt.xa_prnt.xa_prnt.make("tab",properties)
+ else:
+ new_tab=self.xa_prnt.xa_prnt.make("tab",properties)
+ window.tabs().push(new_tab)
+ current.close()
+ returnself
+
+
[docs]defduplicate_to(self,window:'XAChromiumWindow')->'XAChromiumWindow':
+ """Duplicates the tab in the specified window. The tab will then exist in two locations.
+
+ :param window: The window to duplicate the tab in.
+ :type window: XASafariWindow
+ :return: A reference to the tab object.
+ :rtype: XASafariTab
+
+ :Example 1: Duplicate the current tab in the second window
+
+ >>> import PyXA
+ >>> app = PyXA.application("Chromium")
+ >>> tab = app.front_window.active_tab
+ >>> window2 = app.window(1)
+ >>> tab.duplicate_to(window2)
+
+ .. seealso:: :func:`move_to`
+
+ .. versionadded:: 0.0.1
+ """
+ properties={"URL":self.url}
+
+ new_tab=None
+ print(self.xa_prnt)
+ ifisinstance(self.xa_prnt,XABase.XAList):
+ new_tab=self.xa_prnt.xa_prnt.xa_prnt.make("tab",properties)
+ else:
+ new_tab=self.xa_prnt.xa_prnt.make("tab",properties)
+ window.tabs().push(new_tab)
+ returnself
+
+
[docs]defget_clipboard_representation(self)->List[Union[str,AppKit.NSURL]]:
+ """Gets a clipboard-codable representation of the tab.
+
+ When the clipboard content is set to a Chromium tab, the tab's title and URL are added to the clipboard.
+
+ :return: The tab's title and URL
+ :rtype: List[Union[str, AppKit.NSURL]]
+
+ .. versionadded:: 0.0.8
+ """
+ return[self.title,self.url.xa_elem]
[docs]classXAChromiumBookmarkFolderList(XABase.XAList,XAClipboardCodable):
+ """A wrapper around a list of bookmark folders.
+
+ .. seealso:: :class:`XAChromiumBookmarkFolder`
+
+ .. versionadded:: 0.0.3
+ """
+ def__init__(self,properties:dict,filter:Union[dict,None]=None):
+ super().__init__(properties,XAChromiumBookmarkFolder,filter)
+
+
[docs]defid(self)->List[int]:
+ """Gets the ID of each bookmark folder in the list.
+
+ :return: A list of bookmark folder IDs
+ :rtype: List[int]
+
+ .. versionadded:: 0.0.4
+ """
+ returnlist(self.xa_elem.arrayByApplyingSelector_("id"))
+
+
[docs]deftitle(self)->List[str]:
+ """Gets the title of each bookmark folder in the list.
+
+ :return: A list of bookmark folder titles
+ :rtype: List[str]
+
+ .. versionadded:: 0.0.4
+ """
+ returnlist(self.xa_elem.arrayByApplyingSelector_("title"))
+
+
[docs]defindex(self)->List[int]:
+ """Gets the index of each bookmark folder in the list.
+
+ :return: A list of indexes
+ :rtype: List[int]
+
+ .. versionadded:: 0.0.4
+ """
+ returnlist(self.xa_elem.arrayByApplyingSelector_("index"))
+
+
[docs]defby_id(self,id:int)->Union['XAChromiumBookmarkFolder',None]:
+ """Retrieves the bookmark folder whose ID matches the given ID, if one exists.
+
+ :return: The desired bookmark folder, if it is found
+ :rtype: Union[XAChromiumBookmarkFolder, None]
+
+ .. versionadded:: 0.0.4
+ """
+ returnself.by_property("id",id)
+
+
[docs]defby_title(self,title:str)->Union['XAChromiumBookmarkFolder',None]:
+ """Retrieves the first bookmark folder whose title matches the given title, if one exists.
+
+ :return: The desired bookmark folder, if it is found
+ :rtype: Union[XAChromiumBookmarkFolder, None]
+
+ .. versionadded:: 0.0.4
+ """
+ returnself.by_property("title",title)
+
+
[docs]defby_index(self,index:int)->Union['XAChromiumBookmarkFolder',None]:
+ """Retrieves the bookmark folder whose index matches the given index, if one exists.
+
+ :return: The desired bookmark folder, if it is found
+ :rtype: Union[XAChromiumBookmarkFolder, None]
+
+ .. versionadded:: 0.0.4
+ """
+ returnself.by_property("index",index)
+
+
[docs]defget_clipboard_representation(self)->List[str]:
+ """Gets a clipboard-codable representation of each bookmark folder in the list.
+
+ When the clipboard content is set to a list of bookmark folders, each folder's title is added to the clipboard.
+
+ :return: The list of each bookmark folder's title
+ :rtype: List[str]
+
+ .. versionadded:: 0.0.8
+ """
+ returnself.title()
[docs]classXAChromiumBookmarkFolder(XABase.XAObject,XAClipboardCodable):
+ """A class for managing and interacting with bookmark folders in Chromium.app.
+
+ .. seealso:: :class:`XAChromiumApplication`, :class:`XAChromiumBookmarkFolderList`
+
+ .. versionadded:: 0.0.3
+ """
+ def__init__(self,properties):
+ super().__init__(properties)
+ self.id:int#: The unique identifier for the bookmark folder
+ self.title:str#: The name of the bookmark folder
+ self.index:int#: The index of the bookmark folder with respect to its parent folder
+
+ @property
+ defid(self)->int:
+ returnself.xa_elem.id()
+
+ @property
+ deftitle(self)->str:
+ returnself.xa_elem.title()
+
+ @title.setter
+ deftitle(self,title:str):
+ self.set_property("title",title)
+
+ @property
+ defindex(self)->int:
+ returnself.xa_elem.index()
+
+
[docs]defbookmark_folders(self,filter:Union[dict,None]=None)->'XAChromiumBookmarkFolderList':
+ """Returns a list of bookmark folders, as PyXA objects, matching the given filter.
+
+ :param filter: Keys and values to filter folders by, defaults to None
+ :type filter: dict, optional
+ :return: A PyXA list object wrapping a list of bookmark folders
+ :rtype: XAChromiumBookmarkFolderList
+
+ .. versionadded:: 0.0.3
+ """
+ returnself._new_element(self.xa_elem.bookmarkFolders(),XAChromiumBookmarkFolderList,filter)
+
+
[docs]defbookmark_items(self,filter:Union[dict,None]=None)->'XAChromiumBookmarkItemList':
+ """Returns a list of bookmark items, as PyXA objects, matching the given filter.
+
+ :param filter: Keys and values to filter items by, defaults to None
+ :type filter: dict, optional
+ :return: A PyXA list object wrapping a list of bookmark items
+ :rtype: XAChromiumBookmarkItemList
+
+ .. versionadded:: 0.0.3
+ """
+ returnself._new_element(self.xa_elem.bookmarkItems(),XAChromiumBookmarkItemList,filter)
[docs]defget_clipboard_representation(self)->str:
+ """Gets a clipboard-codable representation of the bookmark folder.
+
+ When the clipboard content is set to a bookmark folder, the folders's title is added to the clipboard.
+
+ :return: The bookmark folders's title
+ :rtype: str
+
+ .. versionadded:: 0.0.8
+ """
+ returnself.title
[docs]classXAChromiumBookmarkItemList(XABase.XAList,XAClipboardCodable):
+ """A wrapper around a list of bookmark items.
+
+ .. seealso:: :class:`XAChromiumBookmarkItem`
+
+ .. versionadded:: 0.0.3
+ """
+ def__init__(self,properties:dict,filter:Union[dict,None]=None):
+ super().__init__(properties,XAChromiumBookmarkItem,filter)
+
+
[docs]defid(self)->List[int]:
+ """Gets the ID of each item in the list.
+
+ :return: A list of bookmark item IDs
+ :rtype: List[int]
+
+ .. versionadded:: 0.0.4
+ """
+ returnlist(self.xa_elem.arrayByApplyingSelector_("id"))
+
+
[docs]deftitle(self)->List[str]:
+ """Gets the title of each item in the list.
+
+ :return: A list of bookmark item titles
+ :rtype: List[str]
+
+ .. versionadded:: 0.0.4
+ """
+ returnlist(self.xa_elem.arrayByApplyingSelector_("title"))
+
+
[docs]defurl(self)->List[XABase.XAURL]:
+ """Gets the url of each item in the list.
+
+ :return: A list of bookmark item URLs
+ :rtype: List[XABase.XAURL]
+
+ .. versionadded:: 0.0.4
+ """
+ ls=self.xa_elem.arrayByApplyingSelector_("URL")
+ return[XABase.XAURL(x)forxinls]
+
+
[docs]defindex(self)->List[int]:
+ """Gets the index of each item in the list.
+
+ :return: A list of indexes
+ :rtype: List[int]
+
+ .. versionadded:: 0.0.4
+ """
+ returnlist(self.xa_elem.arrayByApplyingSelector_("index"))
+
+
[docs]defby_id(self,id:int)->Union['XAChromiumBookmarkItem',None]:
+ """Retrieves the bookmark item whose ID matches the given ID, if one exists.
+
+ :return: The desired bookmark item, if it is found
+ :rtype: Union[XAChromiumBookmarkItem, None]
+
+ .. versionadded:: 0.0.4
+ """
+ returnself.by_property("id",id)
+
+
[docs]defby_title(self,title:str)->Union['XAChromiumBookmarkItem',None]:
+ """Retrieves the first bookmark item whose title matches the given title, if one exists.
+
+ :return: The desired bookmark item, if it is found
+ :rtype: Union[XAChromiumBookmarkItem, None]
+
+ .. versionadded:: 0.0.4
+ """
+ returnself.by_property("title",title)
+
+
[docs]defby_url(self,url:XABase.XAURL)->Union['XAChromiumBookmarkItem',None]:
+ """Retrieves the first bookmark item whose URL matches the given URL, if one exists.
+
+ :return: The desired bookmark item, if it is found
+ :rtype: Union[XAChromiumBookmarkItem, None]
+
+ .. versionadded:: 0.0.4
+ """
+ returnself.by_property("URL",str(url.xa_elem))
+
+
[docs]defby_index(self,index:int)->Union['XAChromiumBookmarkItem',None]:
+ """Retrieves the bookmark item whose index matches the given index, if one exists.
+
+ :return: The desired bookmark item, if it is found
+ :rtype: Union[XAChromiumBookmarkItem, None]
+
+ .. versionadded:: 0.0.4
+ """
+ returnself.by_property("index",index)
+
+
[docs]defget_clipboard_representation(self)->List[Union[str,AppKit.NSURL]]:
+ """Gets a clipboard-codable representation of each bookmark item in the list.
+
+ When the clipboard content is set to a list of bookmark items, each item's title and URL are added to the clipboard.
+
+ :return: The list of each bookmark items's title and URL
+ :rtype: List[Union[str, AppKit.NSURL]]
+
+ .. versionadded:: 0.0.8
+ """
+ items=[]
+ titles=self.title()
+ urls=self.url()
+ forindex,titleinenumerate(titles):
+ items.append(title)
+ items.append(urls[index].xa_elem)
+ returnitems
[docs]classXAChromiumBookmarkItem(XABase.XAObject,XAClipboardCodable):
+ """A class for managing and interacting with bookmarks in Chromium.app.
+
+ .. seealso:: :class:`XAChromiumApplication`, :class:`XAChromiumBookmarkItemList`
+
+ .. versionadded:: 0.0.3
+ """
+ def__init__(self,properties):
+ super().__init__(properties)
+ self.id:int#: The unique identifier for the bookmark item
+ self.title:str#: The title of the bookmark item
+ self.url:XABase.XAURL#: The URL of the bookmark
+ self.index:int#: The index of the item with respect to its parent folder
+
+ @property
+ defid(self)->int:
+ returnself.xa_elem.id()
+
+ @property
+ deftitle(self)->str:
+ returnself.xa_elem.title()
+
+ @title.setter
+ deftitle(self,title:str):
+ self.set_property("title",title)
+
+ @property
+ defurl(self)->XABase.XAURL:
+ returnXABase.XAURL(self.xa_elem.URL())
+
+ @url.setter
+ defurl(self,url:XABase.XAURL):
+ self.set_property("URL",url.url)
+
+ @property
+ defindex(self)->int:
+ returnself.xa_elem.index()
+
+
[docs]defget_clipboard_representation(self)->List[Union[str,AppKit.NSURL]]:
+ """Gets a clipboard-codable representation of the bookmark item.
+
+ When the clipboard content is set to a bookmark item, the item's title and URL are added to the clipboard.
+
+ :return: The bookmark items's title and URL
+ :rtype: List[Union[str, AppKit.NSURL]]
+
+ .. versionadded:: 0.0.8
+ """
+ return[self.title,self.url.xa_elem]
:Example 1: Open a local or external URL >>> import PyXA
- >>> app = PyXA.application("Chromium")
+ >>> app = PyXA.Application("Chromium") >>> app.open("https://www.google.com") >>> app.open("google.com") >>> app.open("/Users/exampleuser/Documents/WebPage.html")
@@ -249,7 +256,7 @@
Source code for PyXA.apps.Chromium
self.name:str#: The full title of the windowself.id:int#: The unique identifier for the windowself.index:int#: The index of the window in the front-to-back ordering
- self.bounds:Tuple[Tuple[int,int],Tuple[int,int]]#: The bounding rectangle of the window
+ self.bounds:tuple[int,int,int,int]#: The bounding rectangle of the windowself.closeable:bool#: Whether the window has a close buttonself.minimizable:bool#: Whether the window can be minimizedself.minimized:bool#: Whether the window is currently minimized
@@ -265,6 +272,10 @@
[docs]defid(self)->list[int]:"""Gets the ID of each tab in the list. :return: A list of tab IDs
- :rtype: List[int]
+ :rtype: list[int] .. versionadded:: 0.0.4 """returnlist(self.xa_elem.arrayByApplyingSelector_("id"))
[docs]deftitle(self)->list[str]:"""Gets the title of each tab in the list. :return: A list of tab titles
- :rtype: List[str]
+ :rtype: list[str] .. versionadded:: 0.0.4 """returnlist(self.xa_elem.arrayByApplyingSelector_("title"))
[docs]defurl(self)->list[XABase.XAURL]:"""Gets the URL of each tab in the list. :return: A list of tab URLS
- :rtype: List[XABase.XAURL]
+ :rtype: list[XABase.XAURL] .. versionadded:: 0.0.4 """ls=self.xa_elem.arrayByApplyingSelector_("URL")return[XABase.XAURL(x)forxinls]
[docs]defloading(self)->list[bool]:"""Gets the loading state of each tab in the list. :return: A list of loading states; a list of booleans.
- :rtype: List[bool]
+ :rtype: list[bool] .. versionadded:: 0.0.4 """
@@ -445,13 +496,13 @@
[docs]defget_clipboard_representation(self)->list[Union[str,AppKit.NSURL]]:"""Gets a clipboard-codable representation of each tab in the list. When the clipboard content is set to a list of Chromium tabs, each tab's URL is added to the clipboard. :return: A list of tab URLs
- :rtype: List[Union[str, NSURL]]
+ :rtype: list[Union[str, AppKit.NSURL]] .. versionadded:: 0.0.8 """
@@ -492,6 +543,10 @@
[docs]defget_clipboard_representation(self)->list[Union[str,AppKit.NSURL]]:"""Gets a clipboard-codable representation of the tab. When the clipboard content is set to a Chromium tab, the tab's title and URL are added to the clipboard. :return: The tab's title and URL
- :rtype: List[Union[str, NSURL]]
+ :rtype: list[Union[str, AppKit.NSURL]] .. versionadded:: 0.0.8 """
@@ -705,31 +760,31 @@
[docs]defid(self)->list[int]:"""Gets the ID of each bookmark folder in the list. :return: A list of bookmark folder IDs
- :rtype: List[int]
+ :rtype: list[int] .. versionadded:: 0.0.4 """returnlist(self.xa_elem.arrayByApplyingSelector_("id"))
[docs]deftitle(self)->list[str]:"""Gets the title of each bookmark folder in the list. :return: A list of bookmark folder titles
- :rtype: List[str]
+ :rtype: list[str] .. versionadded:: 0.0.4 """returnlist(self.xa_elem.arrayByApplyingSelector_("title"))
[docs]defindex(self)->list[int]:"""Gets the index of each bookmark folder in the list. :return: A list of indexes
- :rtype: List[int]
+ :rtype: list[int] .. versionadded:: 0.0.4 """
@@ -765,13 +820,13 @@
[docs]defget_clipboard_representation(self)->list[str]:"""Gets a clipboard-codable representation of each bookmark folder in the list. When the clipboard content is set to a list of bookmark folders, each folder's title is added to the clipboard. :return: The list of each bookmark folder's title
- :rtype: List[str]
+ :rtype: list[str] .. versionadded:: 0.0.8 """
@@ -801,6 +856,10 @@
[docs]defid(self)->list[int]:"""Gets the ID of each item in the list. :return: A list of bookmark item IDs
- :rtype: List[int]
+ :rtype: list[int] .. versionadded:: 0.0.4 """returnlist(self.xa_elem.arrayByApplyingSelector_("id"))
[docs]deftitle(self)->list[str]:"""Gets the title of each item in the list. :return: A list of bookmark item titles
- :rtype: List[str]
+ :rtype: list[str] .. versionadded:: 0.0.4 """returnlist(self.xa_elem.arrayByApplyingSelector_("title"))
[docs]defurl(self)->list[XABase.XAURL]:"""Gets the url of each item in the list. :return: A list of bookmark item URLs
- :rtype: List[XABase.XAURL]
+ :rtype: list[XABase.XAURL] .. versionadded:: 0.0.4 """ls=self.xa_elem.arrayByApplyingSelector_("URL")return[XABase.XAURL(x)forxinls]
[docs]defindex(self)->list[int]:"""Gets the index of each item in the list. :return: A list of indexes
- :rtype: List[int]
+ :rtype: list[int] .. versionadded:: 0.0.4 """
@@ -945,13 +1004,13 @@
[docs]defget_clipboard_representation(self)->list[Union[str,AppKit.NSURL]]:"""Gets a clipboard-codable representation of each bookmark item in the list. When the clipboard content is set to a list of bookmark items, each item's title and URL are added to the clipboard. :return: The list of each bookmark items's title and URL
- :rtype: List[Union[str, NSURL]]
+ :rtype: list[Union[str, AppKit.NSURL]] .. versionadded:: 0.0.8 """
@@ -988,10 +1047,18 @@
[docs]defget_clipboard_representation(self)->list[Union[str,AppKit.NSURL]]:"""Gets a clipboard-codable representation of the bookmark item. When the clipboard content is set to a bookmark item, the item's title and URL are added to the clipboard. :return: The bookmark items's title and URL
- :rtype: List[Union[str, NSURL]]
+ :rtype: list[Union[str, AppKit.NSURL]] .. versionadded:: 0.0.8 """
diff --git a/docs/_modules/PyXA/apps/Console 2.html b/docs/_modules/PyXA/apps/Console 2.html
new file mode 100644
index 0000000..d7244db
--- /dev/null
+++ b/docs/_modules/PyXA/apps/Console 2.html
@@ -0,0 +1,124 @@
+
+
+
+
+
+ PyXA.apps.Console — PyXA 0.0.9 documentation
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+