Sessions

In TriliumAlchemy, the Session is the fundamental interface to interact with Trilium. It implements a unit of work pattern, much like SQLAlchemy’s Session.

As you make changes to Trilium objects, their state is maintained in a Session. When you’re done making changes and invoke Session.flush, the unit of work dependency solver determines the order in which to commit changes to Trilium and commits them. For example, new notes need to be created before their attributes.

Note

In Trilium there are 3 kinds of objects, represented in this project as:

These are collectively referred to as “entities”, both in Trilium’s implementation and this project (see BaseEntity).

By default, creating a Session registers it as the default (default=True). Unless a default is registered, it’s required to pass a Session when creating an entity.

Warning

One benefit of the unit of work pattern in databases is the fact that changes can be committed in a transaction. As TriliumAlchemy uses the ETAPI interface provided by Trilium, it’s currently not possible to commit changes within a transaction. This means if an error is encountered, it may leave your notes in an unexpected state with some changes committed and some not.

TriliumAlchemy does its best to validate that changes will be successful, and fail before making any changes if not.

Authentication

Authentication is supported via token or password. If using a password, Trilium will create a token for you on the fly. This token will persist until Session.logout is invoked to delete it, or you exit a context.

Basic usage

Instantiate a Session as follows:

from trilium_alchemy import Session

# your host here
HOST = "http://localhost:8080"

# your token here
TOKEN = "YmcEF6jAWOSv_98jMiIoXEuFHofPqffmjrzS8zOOiLm7Q1DwjS8641YA="

session = Session(HOST, token=TOKEN)

You can then interact with Trilium in various ways as documented in the API. For example, perform a note search to get todos:

todo_list = session.search("#todo")

Then clone them to today’s Day note using Session.get_today_note:

today = session.get_today_note()

today += todo_list

When you’re done making changes, don’t forget to call Session.flush to commit them:

session.flush()

Context manager

The Session implements a context manager, providing a clean way to localize changes and automatically commit them.

For example:

with Session(HOST, token=TOKEN) as session:

    # create a new note under root
    note = Note(title="My note", parents={session.root})

    # session.flush() will be invoked automatically

This creates a new Note as a child of the root note, provided for convenience as Session.root.

Upon exiting the context, changes will automatically be committed via Session.flush.

If you had provided a password instead of token, exiting a context will additionally invoke Session.logout which would otherwise be required in order to delete your temporary token.

Direct ETAPI access

TriliumAlchemy uses an API client generated by OpenAPI Generator to interface with Trilium. This provides Pydantic models and a nice interface generated from Trilium’s etapi.openapi.yaml.

The API object is provided as Session.api for direct ETAPI access, although TriliumAlchemy wraps all supported APIs.