English | 简体中文
Python client for ETAPI of Trilium Note.
- 🐍 trilium-py
- 🦮 Table of Contents
- 🔧 Installation
- 📖 (Basic) Usage
- 🚀 Initialization
- 📊 Application Information
- 🔍 Search note
- 🏭 Create Note
- 👀 Get note
- 🔄 Update note
- 🗑️ Delete note
- 📅 Day note
- 📤 Export note
- 📥 import note
- 💾 Save revision
- 💾 Create data backup
- 🏷 Create attribute
- Get attachment list
- Get attachment info
- Update attachment info
- Get attachment content
- Update attachment content
- Create attachment
- (Advanced Usage) ✅ TODO List
- (Advanced Usage) 🚚 Upload Markdown files
- (Advanced Usage) 🎨 Beautify notes
- (Advanced Usage) 🧹 Sort note content
- (Advanced Usage) 🧹 Delete empty new note
- (Advanced Usage) 🗜️ Optimize image size
- 🛠️ Develop
- 🔗 Original OpenAPI Documentation
python3 -m pip install trilium-py --userThese are basic function that Trilium's ETAPI provides. Down below are some simple example code to use this package.
If you have a ETAPI token, change the server_url and token to yours.
from trilium_py.client import ETAPI
server_url = 'http://localhost:8080'
token = 'YOUR_TOKEN'
ea = ETAPI(server_url, token)If you haven't created ETAPI token, you can create one with your password. Please note, you can only see this token once, please save it if you want to reuse the token.
from trilium_py.client import ETAPI
server_url = 'http://localhost:8080'
password = '1234'
ea = ETAPI(server_url)
token = ea.login(password)
print(token)After initialization, you can use Trilium ETAPI with python now. The following are some examples.
To start with, you can get the application information like this.
print(ea.app_info())It should give you the version of your server application and some extra information.
Search note with keyword.
res = ea.search_note(
search="python",
)
for x in res['results']:
print(x['noteId'], x['title'])Search with regular expression. For example, search and get all child notes under certain note:
res = ea.search_note(
# regular expression search for note title
search="note.title %= '.*'",
ancestorNoteId="Parent Note ID",
fastSearch=False,
limit=1000,
)You can create a simple note like this.
res = ea.create_note(
parentNoteId="root",
title="Simple note 1",
type="text",
content="Simple note example",
noteId="note1"
)The noteId is not mandatory, if not provided, Trilium will generate a random one. You can retrieve it in the return.
noteId = res['note']['noteId']Image note is a special kind of note. You can create an image note with minimal information like this. The image_file
refers to the path of image.
res = ea.create_image_note(
parentNoteId="root",
title="Image note 1",
image_file="shield.png",
)To retrieve the note's content.
ea.get_note_content("noteid")You can get a note metadata by its id.
ea.get_note(note_id)Update note content
ea.update_note_content("noteid", "updated by python")Modify note title
ea.patch_note(
noteId="noteid",
title="Python client moded",
)Simply delete a note by id.
ea.delete_note("noteid")You can get the content of a certain date with get_day_note. The date string should be in format of "%Y-%m-%d", e.g. "
2022-02-25".
ea.get_day_note("2022-02-25")Then set/update a day note with set_day_note. The content should be a (html) string.
ea.set_day_note(date, new_content)Export note comes in two formats html or markdown/md.
res = ea.export_note(
noteId='sK5fn4T6yZRI',
format='md',
save_path='/home/nate/data/1/test.zip',
)This is the built-in feature in trilium. The input file should be a zip file.
res = ea.export_note(
noteId='sK5fn4T6yZRI',
file_path='/home/nate/data/1/test.zip',
)Save note revision manually.
res = ea.save_revision(
noteId='MJzyFRXAVaC9',
)
This example will create a database backup file like this trilium-data/backup/backup-test.db.
res = ea.backup("test")You can use the cron utility in Linux to schedule regular automatic backups. For example, to set up a daily backup at 3: 00 AM, you would use the following cron expression:
0 3 * * * python /path/to/backup-script.pyYou can create a tag for a note
res = ea.create_attribute(
noteId='noteid',
type='label',
name='name_of_the_tag',
value='value_of_the_tag',
isInheritable=True
)The noteId is not mandatory, if not provided, Trilium will generate a random one. You can retrieve it in the return.
noteId = res['note']['noteId']Get all attachments of a single note.
res = ea.get_attachments('uMJt0Ajr1CuC')
Get image title and etc.
res = ea.get_attachment('Y5V6pYq6nwXo')Change image title and etc.
res = ea.update_attachment(
attachmentId='2b7pPzqocS1s', title='hello etapi', role='image', mime='image/png'
)Get the real image file
res = ea.get_attachment_content('icpDE4orQxlI')
with open('1.png', 'wb') as f:
f.write(res)Replace the image with new one
res = ea.update_attachment_content('icWqV6zFtE0V', '/home/nate/data/1.png')Upload a image file as attachment of a note.
res = ea.create_attachment(
ownerId='8m8luXym5LxT',
file_path='/home/nate/data/ksnip_20230630-103509.png',
)With the power of Python, I have expanded the basic usage of ETAPI. You can do something with todo list now.
You can use add_todo to add a TODO item, param is the TODO description
ea.add_todo("买暖宝宝")param is the index of the TODO item
ea.todo_check(0)
ea.todo_uncheck(1)Use update_todo to update a TODO item description at certain index.
ea.update_todo(0, "去码头整点薯条")Remove a TODO item by its index.
ea.delete_todo(1)As the title suggests, you can move yesterday's unfinished things to today. Unfinished todo's will be deleted from yesterday's note.
ea.move_yesterday_unfinished_todo_to_today()You can import Markdown file with images into Trilium now! Trilium-py will help you to upload the images and fix the links for you!
res = ea.upload_md_file(
parentNoteId="root",
file="./md-demo/manjaro 修改caps lock.md",
)You can upload a folder with lots of Markdown files to Trilium and preserve the folder structure!
Say, upload all the notes from VNote, simply do this:
res = ea.upload_md_folder(
parentNoteId="root",
mdFolder="~/data/vnotebook/",
ignoreFolder=['vx_notebook', 'vx_recycle_bin', 'vx_images', '_v_images'],
)Joplin can be imported effortlessly.
res = ea.upload_md_folder(
parentNoteId="root",
mdFolder="/home/nate/data/joplin_data/",
ignoreFolder=['_resources', ],
)res = ea.upload_md_folder(
parentNoteId="root",
mdFolder="/home/nate/data/logseq_data/",
ignoreFolder=['assets', 'logseq'],
)Obsidian has a very unique linking system for files. You should use obsidian-export to convert a Obsidian vault to regular Markdown files. Then you should be able to import the note into Trilium with trilium-py.
Convert it first.
obsidian-export /path/to/your/vault /outThen import just like a normal markdown, trilium-py will handle the images for you.
res = ea.upload_md_folder(
parentNoteId="root",
mdFolder="E:/data/out",
)Youdao does not provide an export feature anymore. Luckily, you can use https://github.com/DeppWang/youdaonote-pull to download your notes and convert them into markdown files. After that, trilium-py should be able to help you import them.
res = ea.upload_md_folder(
parentNoteId="root",
mdFolder="/home/nate/gitRepo/youdaonote-pull/out/",
)You need to convert Turtl from json to markdown first. See turtl-to-markdown for details.
Then you can import with trilium-py like this:
res = ea.upload_md_folder(
parentNoteId="root",
mdFolder="/home/nate/gitRepo/turtl-to-markdown/out/",
ignoreFolder=['_resources'],
)In general, markdown files have variety of standards. You can always try import them with
res = ea.upload_md_folder(
parentNoteId="root",
mdFolder="/home/nate/data/your_markdown_files/",
)If there is any problem, please feel free to create an issue.
Because of the constraints imposed by the library utilized by Trilium, imported notes may experience minor formatting problems. These issues include an additional line appearing at the end of code blocks, images becoming integrated with the note content, and the absence of line breaks between headings, resulting in a cramped appearance of the note content.
Here is what you can do to beautify your note.
Specify a note id to beautify note content.
ea.beautify_note('krm8B9JthNfi')ea.beautify_sub_notes('tlPuzU2szLJh')Sort a note by the heading names. This feature could prove invaluable for notes containing extensive lists, such as book titles sorted into various genres. It's equally useful for managing browser bookmarks or collecting links.
Additionally, you have the option to specify a language code for sorting based on your local language. This enhances the sorting process and tailors it to your linguistic preferences.
res = ea.sort_note_content('lPxtkknjR2bJ')
res = ea.sort_note_content('y6hROhWjNmHQ', 'zh_CN.UTF-8')Sometimes I inadvertently create numerous "new notes" which remain undeleted within my note tree. These "new notes" clutter my workspace, scattered across various locations. I made this bulk deletion of these empty "new notes." Additionally, it generates warning messages for "new notes" that contain content, maybe we should change the title for those notes.
ea.delete_empty_note()Try to reduce image size by using PIL's optimize feature. If the image in your note is not compressed, you can try this. I've successfully convert a note of 44MB to 9.9MB after this process. Backup your data before try this.
The default quality is set to 90.
optimize_image_attachments will keep the original image format and try to compress it.
ea.optimize_image_attachments('uMJt0Ajr1CuC')
To save even more space, you can try the following method.
The optimize_image_attachments_to_webp function converts images to the WebP format, significantly reducing file
sizes. Based on my experience, WebP images can be as little as 25% to 50% of the size of PNG images.
ea.optimize_image_attachments_to_webp('H2q3901uFDCH')
This action can save significant space if you have many clipped pages. Whoever invented WebP is a genius.
Install with pip egg link to make package change without reinstall.
python -m pip install --user -e .The original OpenAPI document is here. You can open it with swagger editor.
