py-appscript

8. Real vs generic references

Real vs. generic references

References may be either 'real' or 'generic'. A real reference relates to a specific application, while a generic reference doesn't. Generic references provide a convenient shortcut for writing literal references without having to specify an application each time.

A real reference begins with an app object that identifies the application whose object(s) it refers to, e.g.:

app('TextEdit').documents.end
app(url='eppc://my-mac.local/Finder').home.folders.name

A generic reference begins with app, con or its and does not identify the application to which it relates, e.g.:

app.documents.end
con.word[3]
its.name.beginswith('d')

Generic references are only evaluated when used used within real references as selectors:

app('Finder').home.folders[its.name.beginswith('d')].get()

app('Tex-Edit Plus').windows[1].text[con.words[2]:con.words[-2]].get()

or as command parameters:

app('TextEdit').make(new=k.word,
    at=app.documents[1].words.end, with_data='Hello')

app('Finder').desktop.duplicate(to=app.home.folders['Desktop Copy'])

Comparing and hashing references

Real application references can be compared for equality and are hashable (so can be used as dictionary keys). For two references to be considered equal, both must have the same application path or url and reference structure. Examples:

print(app('TextEdit').documents[1] == \
    app(id='com.apple.textedit').documents[1].get())
# Result: True; both references evaluate to the same
#     application path and reference

print(app('Finder').home == \
    app('Finder').home.get())
# Result: False; app('Finder').home.get() returns a
#     different reference to the same application object

Generic references cannot be compared or hashed.