`trilium_alchemy.core.session`¶

Implementation of session functionality.

Class index¶

Canonical

Session

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

Symbols¶

class trilium_alchemy.core.session.Session(host: str, token: str | None = None, *, password: str | None = None, default: bool = True, logger: logging.Logger | None = None)¶

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
logger: logging.Logger | None = None: Logger to use, or None to use default logger

Aliases:

trilium_alchemy.Session
trilium_alchemy.core.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 trilium_version: str¶: Trilium version received from server upon session creation.

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

property dirty_count: int¶: Number of dirty BaseEntity objects.

property dirty_set: set[BaseEntity]¶: Copy of 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: 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: 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.

get_dirty_summary() → str¶: Get a summary of entities with pending changes, grouped by note and sorted by title.

trilium_alchemy.core.session¶

Class index¶

Symbols¶

`trilium_alchemy.core.session`¶