`trilium_alchemy.core`#

This module implements ORM access to Trilium and fundamental note capabilities.

Examples in this module assume you have created a Session and that you will either invoke Session.flush or use a context manager to commit the changes.

For example:

session = Session(HOST, token=TOKEN)

...

session.flush()

Or:

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

Class index#

Canonical

Session

Interface to Trilium and context in which to store changes to entities.

Imported

`Note`	`note`	Encapsulates a note and provides a base class for declarative notes.
`Mixin`	`note`	Reusable collection of attributes, children, and fields (`note_id`, `title`, `type`, `mime`) which can be inherited by a `Note`.
`Attribute`	`attribute`	Encapsulates an attribute, a key-value record attached to a note.
`Label`	`attribute`	Encapsulates a label.
`Relation`	`attribute`	Encapsulates a relation.
`Branch`	`branch`	Encapsulates a branch, a parent-child association between notes.
`IconMixin`	`declarative`	Enables setting the attribute `IconMixin.icon` to automatically add as value of `#iconClass` label.
`Entity`	`entity`	Base class for Trilium entities.
`State`	`entity`	Entity state. Maintained automatically based on the user’s updates and object’s current state in Trilium.

Function index#

Imported

`label`	`declarative`	Adds a `Label` to a `Note` or `Mixin` subclass.
`relation`	`declarative`	Adds a `Relation` to a `Note` or `Mixin` subclass.
`label_def`	`declarative`	Adds a `Label` definition (promoted label) to a `Note` or `Mixin` subclass.
`relation_def`	`declarative`	Adds a `Relation` definition (promoted relation) to a `Note` or `Mixin` subclass.
`children`	`declarative`	Add `Note` subclasses as children, implicitly creating a `Branch`.
`child`	`declarative`	Instantiate provided class and add as child, implicitly creating a `Branch` and setting provided kwargs.

Exception index#

Imported

`ReadOnlyError`	`exceptions`	Raised when user attempts to write a field which is read-only.
`ValidationError`	`exceptions`	Raised upon flush when changes in unit of work are invalid or incompatible.

Symbols#

class trilium_alchemy.core.Session(host: str, token: str | None = None, password: str | None = None, default: bool = True)#

Initialization:

Either token or password is required; if both are provided, token takes precedence.

Parameters:

host: str: Hostname of Trilium server
token: str | None = None: ETAPI token
password: str | None = None: Trilium password, if no token provided
default: bool = True: Register this as the default session; in this case, session may be omitted from entity constructors

Aliases:

trilium_alchemy.Session

Interface to Trilium and context in which to store changes to entities.

Changes to entities are tracked as they’re made by the user. The user must then invoke Session.flush to commit them.

For details and example usage, see Sessions in the user guide.

property root: Note#: Helper to lookup root note.

property dirty_count: int#: Number of dirty Entity objects.

property dirty_set: set[Entity]#: All dirty Entity objects.

property dirty_map: dict[State, set[Entity]]#

Mapping of state to dirty Entity objects in that state.

Example usage:

create_set = my_session.dirty_map[State.CREATE]

property host: str#: Host as configured by user.

property api: trilium_client.DefaultApi#: ETAPI client object. Used internally and exposed for manual low-level operations. For its documentation, see: https://github.com/mm21/trilium-client

flush(entities: collections.abc.Iterable[Entity] | None = None)#

Commits pending changes to Trilium via ETAPI.

If entities passed, only flushes those entities and their dependencies.

If entities = None, flushes all dirty entities.

Note

You may equivalently invoke Entity.flush to flush an Entity along with its dependencies.

Parameters:

entities: collections.abc.Iterable[Entity] | None = None: Entities for which to commit changes, internally processed as a set and sorted according to dependencies

search(query: str, order_by: str | None = None, order_direction: Literal[asc, desc] | None = None, limit: int | None = None, fast_search: bool = False, include_archived_notes: bool = False, ancestor_note: Note | None = None, ancestor_depth: int | None = None, debug: bool = False) → list[Note]#

Perform note search using query string as described at: https://github.com/zadam/trilium/wiki/Search

Parameters:

query: str: Query string
order_by: str | None = None: Name of the property/label to order search results by
order_direction: Literal[asc, desc] | None = None: Ascending ("asc") or descending ("desc"), ascending by default
limit: int | None = None: Limit the number of results to receive
fast_search: bool = False: Enable fast search (doesn’t search content)
include_archived_notes: bool = False: Include archived notes
ancestor_note: Note | None = None: Search only in subtree of provided note
ancestor_depth: int | None = None: Define how deep in the tree should the notes be searched
debug: bool = False: Get debug information in the response (search query parsing)

Returns:

list[Note]

List of notes

backup(name: str)#

Create backup with provided name, e.g. now will write backup-now.db.

Parameters:

name: str: Name of backup to write

export_zip(note: Note, dest_path: str, export_format: Literal[html, markdown] = 'html')#

Export note subtree to zip file.

Note

You can equivalently invoke Note.export_zip.

Parameters:

note: Note: Root of source subtree
dest_path: str: Destination .zip file
export_format: Literal[html, markdown] = 'html': Format of exported HTML notes

import_zip(note: Note, src_path: str)#

Import note subtree from zip file, discarding its current state.

Note

You can equivalently invoke Note.import_zip.

Parameters:

note: Note: Root of destination subtree
src_path: str: Source .zip file

get_today_note() → Note#: Returns today’s day note. Gets created if doesn’t exist.

get_day_note(date: datetime.date) → Note#

Returns a day note for a given date. Gets created if doesn’t exist.

Parameters:

date: datetime.date: Date object, e.g. datetime.date(2023, 7, 5)

get_week_note(date: datetime.date) → Note#

Returns a week note for a given date. Gets created if doesn’t exist.

Parameters:

date: datetime.date: Date object, e.g. datetime.date(2023, 7, 5)

get_month_note(month: str) → Note#

Returns a month note for a given date. Gets created if doesn’t exist.

Parameters:

month: str: Month in the form yyyy-mm, e.g. 2023-07

get_year_note(year: str) → Note#

Returns a year note for a given date. Gets created if doesn’t exist.

Parameters:

year: str: Year as string

get_inbox_note(date: datetime.date) → Note#

Returns an “inbox” note into which note can be created. Date will be used depending on whether the inbox is a fixed note (identified with #inbox label) or a day note in a journal.

Parameters:

date: datetime.date: Date object, e.g. datetime.date(2023, 7, 5)

get_app_info() → trilium_client.models.app_info.AppInfo#: Returns app info. See https://github.com/mm21/trilium-client/blob/main/docs/AppInfo.md for its definition.

refresh_note_ordering(note: Note) → None#: Refresh ordering of provided note’s children for any connected clients.

Note

This API is automatically invoked after any child branch positions are adjusted. It should rarely be required, but is provided for completeness.

classmethod login(host: str, password: str) → str#

Note

You can implicitly login by passing password when creating a Session. This API should rarely be required, but is provided for completeness.

Parameters:

host: str: Hostname of Trilium server
password: str: Trilium password

Returns:

str

ETAPI token

logout()#

Deletes the currently active API token, if this Session was created with a password rather than token.

Warning

Subsequent attempts to invoke ETAPI methods using this Session, such as those invoked by flush, will fail.

If this Session was instead created with a token, a warning will be generated and no action will be taken. For token-based sessions there’s no corresponding login.

deregister_default()#: If this session was registered as default, deregister it. No-op otherwise.

trilium_alchemy.core#

Class index#

Function index#

Exception index#

Symbols#

`trilium_alchemy.core`#