`trilium_alchemy.core`¶

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

See the User guide for a detailed walkthrough with examples.

Class index¶

Canonical

Session

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

Imported

`Note`	`note`	Encapsulates a note. Can be subclassed for custom attribute accessors.
`BaseAttribute`	`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.
`BaseDeclarativeNote`	`declarative.base`	Note to use as subclass for declarative notes, i.e. note classes which automatically sync with the corresponding note if it already exists in Trilium.
`BaseDeclarativeMixin`	`declarative.base`	Reusable collection of attributes and children which can be inherited by a `BaseDeclarativeNote`.
`BaseEntity`	`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.decorators`	Adds a `Label` to a `BaseDeclarativeNote` or `BaseDeclarativeMixin` subclass.
`relation`	`declarative.decorators`	Adds a `Relation` to a `BaseDeclarativeNote` or `BaseDeclarativeMixin` subclass.
`label_def`	`declarative.decorators`	Adds a `Label` definition (promoted label) to a `BaseDeclarativeNote` or `BaseDeclarativeMixin` subclass.
`relation_def`	`declarative.decorators`	Adds a `Relation` definition (promoted relation) to a `BaseDeclarativeNote` or `BaseDeclarativeMixin` subclass.
`children`	`declarative.decorators`	Add `BaseDeclarativeNote` subclasses as children, implicitly creating a `Branch`. May use a tuple of `(child_cls, prefix)` to additionally set branch prefix.
`child`	`declarative.decorators`	Instantiate provided class and add as child, 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 BaseEntity objects.

property dirty_set: set[BaseEntity]¶: All dirty BaseEntity objects.

property dirty_map: dict[State, set[BaseEntity]]¶

Mapping of state to dirty BaseEntity 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[BaseEntity] | 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 BaseEntity along with its dependencies.

Parameters:

entities: collections.abc.Iterable[BaseEntity] | 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

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)¶: 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`¶