pydt4 0.1.0__tar.gz

pydt4-0.1.0/PKG-INFO

@@ -0,0 +1,5 @@
+Metadata-Version: 2.4
+Name: pydt4
+Version: 0.1.0
+Summary: Direct DEVONthink Apple Events via ctypes
+Requires-Python: >=3.10

pydt4-0.1.0/README.md

@@ -0,0 +1,18 @@
+# pydt4
+
+A macOS Python interface to DEVONthink using Foundation's native Apple Event descriptors through `ctypes`. No PyObjC, JXA, or external runtime dependencies are required.
+
+```python
+from pydt4 import DEVONthink, Record
+app = DEVONthink()  # or bundle_id="com.devon-technologies.think3"
+db = app.databases[0]
+print(db.records.batch_get("name"))
+record: Record = db.records[0]
+print(record.name)
+unread = db.records.whose((Record.unread == True) & Record.name.contains("project"))
+print(unread.pluck("name", "uuid"))
+```
+
+Object and collection references are lazy. `batch_get` fetches a property for all collection elements in one Apple Event. `pluck` makes one request per property. macOS may ask for Automation permission when sending to DEVONthink. For deterministic tests, pass `sender=` to `DEVONthink` or `AEBridge`; it receives the actual event descriptor and returns a reply descriptor.
+
+Run deterministic tests with `python3 -m unittest discover -s tests -v`. Run `scripts/test-live.sh` to build an on-demand, entitled helper and execute the read-only DEVONthink integration tests without copying commands into another terminal. macOS may request Automation permission for `Pydt4LiveTests`; after testing is finished, `scripts/test-live.sh --cleanup` revokes that permission and removes the helper.

pydt4-0.1.0/pydt4/__init__.py

@@ -0,0 +1,8 @@
+"""Direct, dependency-free DEVONthink Apple Event interface."""
+from .aevent import (
+    AEBridge, AEDescriptor, AERecord, examined_spec, examined_prop_spec,
+    cmp_spec, logic_spec, whose_spec, AppleEventError, AppleEventPermissionError,
+    AppleEventTimeoutError, AppleEventObjectNotFoundError, EnumValue,
+)
+from .sdef import load_script_suite, resolve_enum
+from .models import AEObject, AEReadOnly, AEProp, AEElements, AEFilter, FilteredElements, ViewerWindow, DEVONthink, DEVONthink3, Database, Record, SmartGroup, TagGroup, Reminder, ThinkWindow, DocumentWindow, ThinkTab, TextStorage, ElementArray

pydt4-0.1.0/pydt4/aevent.py

@@ -0,0 +1,207 @@
+"""Direct NSAppleEventDescriptor construction and Apple Event transport."""
+import ctypes as C
+import struct
+import sys
+from datetime import datetime
+from pathlib import Path
+from dataclasses import dataclass
+from .objc import (cls, send, nsstr, pystr, nsdata_to_bytes, osstatus_info,
+                   datetime_to_nsdate, nsdate_to_datetime, path_to_nsurl,
+                   nsurl_to_path, autorelease_pool)
+
+D = cls('NSAppleEventDescriptor')
+def fourcc(code):
+    b = code.encode('mac_roman') if isinstance(code, str) else bytes(code)
+    if len(b) != 4: raise ValueError('FourCC must be exactly four bytes')
+    return int.from_bytes(b, 'big')
+def uncode(value): return value.to_bytes(4, 'big').decode('mac_roman')
+
+class AEDescriptor:
+    def __init__(self, ptr):
+        if not ptr: raise ValueError('nil NSAppleEventDescriptor')
+        self.ptr = send(ptr, 'retain')
+    def __del__(self):
+        if getattr(self, 'ptr', None): send(self.ptr, 'release', restype=None)
+    @property
+    def type(self): return send(self.ptr, 'descriptorType', restype=C.c_uint32)
+    @property
+    def data(self): return nsdata_to_bytes(send(self.ptr, 'data'))
+    def coerce(self, code):
+        p = send(self.ptr, 'coerceToDescriptorType:', fourcc(code), argtypes=(C.c_uint32,))
+        return AEDescriptor(p) if p else None
+    def keyword(self, code):
+        p = send(self.ptr, 'descriptorForKeyword:', fourcc(code), argtypes=(C.c_uint32,))
+        return AEDescriptor(p) if p else None
+    def param(self, code):
+        p = send(self.ptr, 'paramDescriptorForKeyword:', fourcc(code), argtypes=(C.c_uint32,))
+        return AEDescriptor(p) if p else None
+    def attribute(self, code):
+        p = send(self.ptr, 'attributeDescriptorForKeyword:', fourcc(code), argtypes=(C.c_uint32,))
+        return AEDescriptor(p) if p else None
+    def item(self, i):
+        p = send(self.ptr, 'descriptorAtIndex:', i, argtypes=(C.c_long,))
+        return AEDescriptor(p) if p else None
+    @property
+    def count(self): return send(self.ptr, 'numberOfItems', restype=C.c_long)
+    def put(self, code, value):
+        send(self.ptr, 'setDescriptor:forKeyword:', value.ptr, fourcc(code), restype=None, argtypes=(C.c_void_p,C.c_uint32))
+    def put_param(self, code, value):
+        send(self.ptr, 'setParamDescriptor:forKeyword:', value.ptr, fourcc(code), restype=None, argtypes=(C.c_void_p,C.c_uint32))
+    def append(self, value):
+        send(self.ptr, 'insertDescriptor:atIndex:', value.ptr, 0, restype=None, argtypes=(C.c_void_p,C.c_long))
+    @classmethod
+    def raw(cls_, typ, data):
+        return cls_(send(D,'descriptorWithDescriptorType:bytes:length:',fourcc(typ),data,len(data),argtypes=(C.c_uint32,C.c_char_p,C.c_ulong)))
+    @classmethod
+    def ordinal(cls_, code): return cls_.raw('abso', fourcc(code).to_bytes(4,sys.byteorder))
+
+def factory(selector, *args, argtypes=()): return AEDescriptor(send(D,selector,*args,argtypes=argtypes))
+def typecode(code): return factory('descriptorWithTypeCode:',fourcc(code),argtypes=(C.c_uint32,))
+def enumcode(code): return factory('descriptorWithEnumCode:',fourcc(code),argtypes=(C.c_uint32,))
+@dataclass(frozen=True)
+class EnumValue:
+    code: str
+
+class AERecord(dict):
+    """An Apple Event record with explicit FourCC keywords."""
+
+def pack(value):
+    if isinstance(value, AEDescriptor): return value
+    if hasattr(value, '_spec'): return value._spec
+    if value is None: return factory('nullDescriptor')
+    if isinstance(value, EnumValue): return enumcode(value.code)
+    if isinstance(value, bool): return factory('descriptorWithBoolean:',value,argtypes=(C.c_bool,))
+    if isinstance(value, int):
+        if -(2**31) <= value < 2**31: return factory('descriptorWithInt32:',value,argtypes=(C.c_int32,))
+        return AEDescriptor.raw('comp',struct.pack('=q',value))
+    if isinstance(value,float): return AEDescriptor.raw('doub',struct.pack('=d',value))
+    if isinstance(value,str): return factory('descriptorWithString:',nsstr(value),argtypes=(C.c_void_p,))
+    if isinstance(value,bytes): return AEDescriptor.raw('tdta',value)
+    if isinstance(value,datetime):
+        return factory('descriptorWithDate:',datetime_to_nsdate(value),argtypes=(C.c_void_p,))
+    if isinstance(value,Path):
+        return factory('descriptorWithFileURL:',path_to_nsurl(value),argtypes=(C.c_void_p,))
+    if isinstance(value,(list,tuple)):
+        d=factory('listDescriptor')
+        for v in value: d.append(pack(v))
+        return d
+    if isinstance(value,AERecord):
+        d=factory('recordDescriptor')
+        for k,v in value.items(): d.put(k,pack(v))
+        return d
+    if isinstance(value,dict):
+        d=factory('recordDescriptor'); user=[]
+        for k,v in value.items(): user.extend((k,v))
+        if user: d.put('usrf',pack(user))
+        return d
+    raise TypeError(f'Cannot pack {type(value).__name__}')
+
+def spec(want, form, selection, container=None):
+    r=factory('recordDescriptor')
+    for k,v in [('want',typecode(want)),('from',pack(container)),('form',enumcode(form)),('seld',selection)]: r.put(k,v)
+    result=r.coerce('obj ')
+    if not result: raise ValueError('Could not coerce object specifier')
+    return result
+def prop_spec(code, container=None): return spec('prop','prop',typecode(code),container)
+def index_spec(want,index,container=None): return spec(want,'indx',pack(index),container)
+def all_spec(want,container=None): return spec(want,'indx',AEDescriptor.ordinal('all '),container)
+def id_spec(want,unique_id,container=None): return spec(want,'ID  ',pack(unique_id),container)
+def name_spec(want,name,container=None): return spec(want,'name',pack(name),container)
+
+def examined_spec(): return AEDescriptor.raw('exmn',b'')
+def examined_prop_spec(code): return prop_spec(code,examined_spec())
+def cmp_spec(op_code,obj1,obj2):
+    r=factory('recordDescriptor')
+    for k,v in [('relo',enumcode(op_code)),('obj1',pack(obj1)),('obj2',pack(obj2))]: r.put(k,v)
+    return r.coerce('cmpd')
+def logic_spec(op_code,terms):
+    r=factory('recordDescriptor')
+    for k,v in [('logc',enumcode(op_code)),('term',pack(list(terms)))]: r.put(k,v)
+    return r.coerce('logi')
+def whose_spec(want,test_desc,container=None): return spec(want,'test',test_desc,container)
+
+def unpack(d, bridge=None):
+    if d is None: return None
+    t=uncode(d.type); b=d.data
+    if t in ('null','msng'): return None
+    if t in ('bool','true','fals'): return t=='true' or (t=='bool' and bool(b[0]))
+    if t in ('long','shor','comp','magn'): return int.from_bytes(b,sys.byteorder,signed=t!='magn')
+    if t in ('doub','sing'): return struct.unpack('=d' if t=='doub' else '=f',b)[0]
+    if t in ('utxt','TEXT','utf8','ctxt'): return pystr(send(d.ptr,'stringValue'))
+    if t in ('tdta','rdat','pgPD'): return b
+    if t=='ldt ': return nsdate_to_datetime(send(d.ptr,'dateValue'))
+    if t=='furl': return nsurl_to_path(send(d.ptr,'fileURLValue'))
+    if t in ('enum','type'): return EnumValue(uncode(int.from_bytes(b,sys.byteorder)))
+    if t=='list': return [unpack(d.item(i),bridge) for i in range(1,d.count+1)]
+    if t=='reco':
+        result={}
+        for i in range(1,d.count+1):
+            key=uncode(send(d.ptr,'keywordForDescriptorAtIndex:',i,restype=C.c_uint32,argtypes=(C.c_long,)))
+            val=unpack(d.item(i),bridge)
+            if key=='usrf' and isinstance(val,list): result.update(zip(val[::2],val[1::2]))
+            else: result[key]=val
+        return result
+    if t=='obj ':
+        from .models import object_for_spec
+        return object_for_spec(bridge,d)
+    return d
+
+class AppleEventError(Exception):
+    def __init__(self, code, message='', event_class=None, event_id=None):
+        if message is not None: message = str(message)
+        symbol, comment = (None, None) if code == -1 and message else osstatus_info(code)
+        if not message:
+            message = ': '.join(p for p in (symbol, comment) if p) or 'Apple Event failed'
+        elif symbol and symbol not in message:
+            message = f'{symbol}: {message}'
+        self.code, self.symbol, self.message = code, symbol, message
+        self.event_class, self.event_id = event_class, event_id
+        loc = f' {event_class}/{event_id}' if event_class and event_id else ''
+        super().__init__(f'Apple Event{loc} ({code}): {message}')
+
+class AppleEventPermissionError(AppleEventError, PermissionError): pass
+class AppleEventTimeoutError(AppleEventError, TimeoutError): pass
+class AppleEventObjectNotFoundError(AppleEventError, LookupError): pass
+
+_ERROR_CLASSES = {
+    -1743: AppleEventPermissionError,
+    -1744: AppleEventPermissionError,
+    -1712: AppleEventTimeoutError,
+    -1728: AppleEventObjectNotFoundError,
+    -1719: AppleEventObjectNotFoundError,
+}
+
+def make_apple_event_error(code, message='', event_class=None, event_id=None):
+    err_cls = _ERROR_CLASSES.get(code, AppleEventError)
+    return err_cls(code, message, event_class, event_id)
+
+class AEBridge:
+    def __init__(self,bundle_id=None,*,sender=None,timeout=60.0):
+        if bundle_id is None:
+            import os
+            bundle_id='com.devon-technologies.think' if os.path.exists('/Applications/DEVONthink.app') else 'com.devon-technologies.think3'
+        self.bundle_id,self.sender,self.timeout=bundle_id,sender,timeout
+    def event(self,event_class,event_id,direct=None,**kwargs):
+        with autorelease_pool():
+            target=factory('descriptorWithBundleIdentifier:',nsstr(self.bundle_id),argtypes=(C.c_void_p,))
+            event=factory('appleEventWithEventClass:eventID:targetDescriptor:returnID:transactionID:',fourcc(event_class),fourcc(event_id),target.ptr,-1,0,argtypes=(C.c_uint32,C.c_uint32,C.c_void_p,C.c_int16,C.c_int32))
+            if direct is not None: event.put_param('----',pack(direct))
+            for k,v in kwargs.items():
+                if v is not None: event.put_param(k,pack(v))
+            reply=self.send_event(event)
+            err=reply.param('errn')
+            if err and unpack(err):
+                msg=reply.param('errs'); raise make_apple_event_error(unpack(err),unpack(msg) if msg else '',event_class,event_id)
+            return unpack(reply.param('----'),self)
+    def send_event(self,event):
+        if self.sender is not None: return self.sender(event,self.timeout)
+        error=C.c_void_p()
+        p=send(event.ptr,'sendEventWithOptions:timeout:error:',0x23,self.timeout,C.byref(error),argtypes=(C.c_ulong,C.c_double,C.c_void_p))
+        if not p:
+            code=send(error.value,'code',restype=C.c_long) if error.value else -1
+            message=pystr(send(error.value,'localizedDescription')) if error.value else 'Apple Event send failed without NSError'
+            raise make_apple_event_error(code,message)
+        return AEDescriptor(p)
+    def get(self,spec): return self.event('core','getd',spec)
+    def set(self,spec,value): return self.event('core','setd',spec, data=value)
+    def count(self,container,want): return self.event('core','cnte',container, kocl=typecode(want))