{"id":14865237,"url":"https://github.com/thekoc/devonthink-python","last_synced_at":"2025-09-18T20:32:23.032Z","repository":{"id":160090920,"uuid":"635052179","full_name":"thekoc/devonthink-python","owner":"thekoc","description":"Python API for Devonthink 3 utilizes AppleScript (JXA) and PyObjC.","archived":false,"fork":false,"pushed_at":"2024-02-18T06:46:37.000Z","size":5077,"stargazers_count":54,"open_issues_count":0,"forks_count":5,"subscribers_count":5,"default_branch":"main","last_synced_at":"2025-01-09T08:42:51.429Z","etag":null,"topics":["applescript","devonthink","python"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/thekoc.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null}},"created_at":"2023-05-01T21:27:21.000Z","updated_at":"2024-12-09T10:41:40.000Z","dependencies_parsed_at":"2024-02-15T10:41:28.469Z","dependency_job_id":null,"html_url":"https://github.com/thekoc/devonthink-python","commit_stats":null,"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thekoc%2Fdevonthink-python","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thekoc%2Fdevonthink-python/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thekoc%2Fdevonthink-python/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thekoc%2Fdevonthink-python/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/thekoc","download_url":"https://codeload.github.com/thekoc/devonthink-python/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":233520027,"owners_count":18688532,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["applescript","devonthink","python"],"created_at":"2024-09-20T00:02:10.732Z","updated_at":"2025-09-18T20:32:21.969Z","avatar_url":"https://github.com/thekoc.png","language":"Python","readme":"# PyDT3 - The Python API For DEVONthink 3\n\nThis project aims to let you use Python to interact with DEVONthink 3 with ease.\n\nUlike many other API wrapper projects, PyDT3 is documented through docstring. Therefore can benefit from code completion and documentation in code editors.\n\n![documentation-in-editor-2](https://github.com/thekoc/devonthink-python/raw/main/images/docstring_example_2.png)\n![documentation-in-editor-3](https://github.com/thekoc/devonthink-python/raw/main/images/docstring_example_3.png)\n\nTo install, just run\n\n```python\npip install pydt3\n```\n\nMost of the classes and methods map directly to the AppleScript APIs.\n\nFor example:\n\n```python\nfrom pydt3 import DEVONthink3\n\ndt3 = DEVONthink3()\n\nfor db in dt3.databases:\n    print(db.name)\n\nselected_record = dt3.selected_records[0]\nprint(selected_record.name)\n```\n\n```applescript\ntell application \"DEVONthink 3\"\n    repeat with db in databases\n        log name of db as string\n    end repeat\n    set selected_record to item 1 of selected records\n    log name of selected_record as string\nend tell\n```\n\nThese two scripts do the same thing.\n\nThe project is still in early stage. Not all properties and methods have been implemented.\n\n## Installation\n\n### Pip\n\n```bash\npip install pydt3\n```\n\n## Quick Start\n\n```python\nfrom pydt3 import DEVONthink3\ndtp3 = DEVONthink3()\n\ninbox = dtp3.inbox\n\n# create a new folder in inbox\ndtp3.create_location('new-group-from-pydt3', inbox)\n\n# get selected records\nrecords = dtp3.selected_records\n\n# get the first selected record and print its information\nif records:\n    first = records[0]\n    print(first.name)\n    print(first.type)\n    print(first.reference_url)\n    print(first.plain_text)\n\n# create record in inbox\nrecord = dtp3.create_record_with({\n    'name': 'hello-from-pydt3',\n    'type': 'markdown',\n    'plain text': '# Hello from pydt3',\n}, inbox)\n```\n\n## Requirements\n\n- DEVONthink 3\n- Python 3.7+\n- PyObjC\n\n(See `requirements.txt` for more information.)\n\n## Work With ChatGPT\n\n### Add Tags to Selected Records Using ChatGPT\n\nPut this [script](https://github.com/thekoc/devonthink-python/releases/download/example-scripts-v0.03/GPT.Add.Tags.scptd.zip) into `~/Library/Application Scripts/com.devon-technologies.think3/Contextual Menu` and run it from contextual menu in DEVONthink (The record must be in selected state).\n\n![add_tags_contextual_menu](https://github.com/thekoc/devonthink-python/raw/main/images/add_tags_contextual_menu.png)\n\nAnd voilà, the tags are added based on contents automatically.\n\n![generated_tags](https://github.com/thekoc/devonthink-python/raw/main/images/generated_tags.png)\n\nNote: You are required to have an [API key](https://platform.openai.com/account/api-keys) from OpenAI. The first time you run the script, a prompt will ask you to enter key.\n\n![api_key_prompt](https://github.com/thekoc/devonthink-python/raw/main/images/api_key_prompt.png)\n\nThe key will be store in Incoming group for DEVONthink (usually `Inbox`). You can see the file `__openai_api_key__` generated there. You can move it to other opened database but don't change it's name.\n\n### Auto Writing / Summarizing Using ChatGTP\n\n[This script](https://github.com/thekoc/devonthink-python/releases/download/example-scripts-v0.03/GPT.Expand.Content.zip) lets you to insert `\u003c\u003cTOKEN\u003e\u003e` into your text and then generate the text based on the token.\n\n![before_expansion](https://github.com/thekoc/devonthink-python/raw/main/images/before_expansion.png)\n\n![after_expansion](https://github.com/thekoc/devonthink-python/raw/main/images/after_expansion.png)\n\nPut the script into `~/Library/Application Scripts/com.devon-technologies.think3/Toolbar`. Restart the DEVONthink and you will see the script in the toolbar customization window.\n\n![custom_toolbar](https://github.com/thekoc/devonthink-python/raw/main/images/custom_toolbar.png)\n\n### About the Release Scripts\n\nThe script bundles provided by the project are packed by PyInstaller so that you can run them without Python installation. But the size is relatively large. You can write your own version if you do have Python installed (with required packages.) See codes in examples for more information.\n\n## Remarks\n\nFor those properties that are not implemented, you can still use the through the fallback method. Just that you cannot use the python style naming convention (Basically it will pass the python names directly to JXA).\n\n```python\n# a.propertyName (int) is not implemented in PyDT3.\np = a.propertyName()\na.propertyName = (p + 1)\n\n```\n\nThis project uses PyObjC to execute AppleScript code in Objective-C then wrap them in Python.\n\nThe bridging part is inspired by [py-applescript](https://github.com/rdhyee/py-applescript).\n\nMany of the APIs are generated by ChatGPT from the DEVONthink's AppleScript dictionary.\n\nNotes used as examples are imported from [The Blue Book](https://github.com/lyz-code/blue-book), a personal wiki shared by [lyz-code](https://github.com/lyz-code).\n\n## Limitations\n\n- The APIs are not fully tested. Please report any issues.\n- ~~Rich texts in AppleScript are converted to strings in Python, which causes style information loss.~~\n\n    Now rich text is partially supported.\n\n- ~~Collections of elements (eg. `database.records`) are converted to lists in Python. While in Applescript they are retrieved in a lazy manner. This may cause performance issues with large collections.~~\n\n    Now they are wrapped in an `OSAObjArray` object and are evaluated lazily.\n\n## TODO\n\n- [ ] Implement all APIs\n- [ ] Ability to execute JXA code snippets.\n- [ ] `whose` filter for `OSAObjArray` container.\n","funding_links":[],"categories":["Python"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fthekoc%2Fdevonthink-python","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fthekoc%2Fdevonthink-python","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fthekoc%2Fdevonthink-python/lists"}