`trilium_alchemy.core.declarative`¶

Class index¶

Canonical

`BaseDeclarativeNote`	Note to use as subclass for declarative notes which deterministically create a note hierarchy with fixed ids.
`BaseDeclarativeMixin`	Reusable collection of attributes and children which can be inherited by a `BaseDeclarativeNote`.

Function index¶

Canonical

`label`	Adds a `Label` to a `BaseDeclarativeNote` or `BaseDeclarativeMixin` subclass.
`relation`	Adds a `Relation` to a `BaseDeclarativeNote` or `BaseDeclarativeMixin` subclass.
`label_def`	Adds a `Label` definition (promoted label) to a `BaseDeclarativeNote` or `BaseDeclarativeMixin` subclass.
`relation_def`	Adds a `Relation` definition (promoted relation) to a `BaseDeclarativeNote` or `BaseDeclarativeMixin` subclass.
`children`	Add `BaseDeclarativeNote` subclasses as children, implicitly creating a `Branch`. May use a tuple of `(child_cls, prefix)` to additionally set branch prefix.
`child`	Instantiate provided class and add as child, creating a `Branch` and setting provided kwargs.

Symbols¶

Initialization:

Parameters:

title: Note title
note_type: Note type, default text; one of: "text", "code", "relationMap", "search", "render", "book", "mermaid", "canvas", "file", "image"
mime: MIME type, default text/html; needs to be specified only for note types "text", "code", "file", "image"
parents: Parent note/branch, or iterable of notes/branches (internally modeled as a set)
children: Iterable of child notes/branches (internally modeled as a list)
attributes: Iterable of attributes (internally modeled as a list)
content: Text/binary content or file handle
attachments: Iterable of attachments (internally modeled as a list); items may be an Attachment, a pathlib.Path, or a binary file handle with a .name
note_id: noteId to use, will create if it doesn’t exist
template: Note to set as target of ~template relation
session: Session, or None to use default
kwargs: Internal only

Bases:

trilium_alchemy.core.note.Note
trilium_alchemy.core.declarative.BaseDeclarativeMixin

Aliases:

trilium_alchemy.BaseDeclarativeNote
trilium_alchemy.core.BaseDeclarativeNote

Note to use as subclass for declarative notes which deterministically create a note hierarchy with fixed ids.

Note

Subclassing this class means the note will replace any existing fields (title, type, mime, content) as well as attributes and children. Set leaf = True to preserve children.

Todo

Add auto_mime=True to also set mime using magic package (or do so automatically if BaseDeclarativeNote.content_file set, but BaseDeclarativeNote.mime_ not set)

note_id_: str | None¶

None

note_id to explicitly assign.

title_: str | None¶

None

Title to set, or None to use class name.

note_type_: str | None¶

None

Note type to set.

mime_: str | None¶

None

MIME type to set.

content_: str | bytes | None¶

None

Content to set.

content_file: str | None¶

None

Name of file to use as content, relative to module’s location.

Also adds #originalFilename label.

Note

Currently Trilium only shows #originalFilename if the note’s type is file.

note_id_seed: str | None¶

None

Seed from which to generate note_id.

Useful to generate a collision-avoidant id from a human-friendly identifier. Generated as base64-encoded hash of seed.

note_id_segment: str | None¶

None

Segment with which to generate note_id given the parent’s note_id, if no note_id is otherwise specified.

singleton: bool¶

False

If set on a BaseDeclarativeNote subclass, enables deterministic calculation of note_id based on the fully qualified class name. This means the same class will always have the same note_id when instantiated.

Warning

If you move this class to a different module, it will result in a different note_id which will break any non-declarative relations to it. To enable more portable behavior, set BaseDeclarativeNote.idempotent or assign BaseDeclarativeNote.note_id_seed explicitly.

idempotent: bool¶

False

If set on a BaseDeclarativeNote subclass, enables deterministic calculation of note_id based on the class name.

Similar to BaseDeclarativeNote.singleton, but only the class name (not fully qualified) is used.

idempotent_segment: bool¶

False

If set on a BaseDeclarativeNote subclass, sets segment name to class name for the purpose of note_id calculation.

An explicitly provided BaseDeclarativeNote.note_id_segment takes precedence.

leaf: bool¶

False

If set to True on a BaseDeclarativeNote subclass, disables setting of child notes declaratively, allowing children to be manually maintained by the user. Otherwise, notes added by the user will be deleted to match the children added declaratively.

Should be set on notes intended to hold user notes, e.g. todo lists.

hide_new_note: bool¶

False

Whether to hide “new note” button, regardless of whether it would otherwise be hidden.

Can be used to hide “new note” button for e.g. Templates which otherwise would show it.

icon: str | None¶

None

Inherited from: trilium_alchemy.core.declarative.BaseDeclarativeMixin

If provided, adds #iconClass label unless it is already present.

property note_id_seed_final: str | None¶

Get the seed from which this note’s id was derived.

Useful for debugging.

property note_id: str | None¶

Inherited from: trilium_alchemy.core.note.Note

Getter for noteId, or None if not created yet.

property title: str¶

Inherited from: trilium_alchemy.core.note.Note

Getter/setter for note title.

property note_type: str¶

Inherited from: trilium_alchemy.core.note.Note

Getter/setter for note title.

property mime: str¶

Inherited from: trilium_alchemy.core.note.Note

Getter/setter for MIME type.

property is_protected: bool¶

Inherited from: trilium_alchemy.core.note.Note

Protected state, can only be changed in Trilium UI.

property date_created: str | None¶

Inherited from: trilium_alchemy.core.note.Note

Local created datetime, e.g. 2021-12-31 20:18:11.939+0100.

property date_modified: str | None¶

Inherited from: trilium_alchemy.core.note.Note

Local modified datetime, e.g. 2021-12-31 20:18:11.939+0100.

property utc_date_created: str | None¶

Inherited from: trilium_alchemy.core.note.Note

UTC created datetime, e.g. 2021-12-31 19:18:11.939Z.

property utc_date_modified: str | None¶

Inherited from: trilium_alchemy.core.note.Note

UTC modified datetime, e.g. 2021-12-31 19:18:11.939Z.

property attributes: Attributes¶

Inherited from: trilium_alchemy.core.note.Note

Getter/setter for attributes, both owned and inherited.

Setter:: Sets list of owned attributes, replacing the existing list

property labels: Labels¶

Inherited from: trilium_alchemy.core.note.Note

Getter for labels, accessed as combined list or filtered by owned vs inherited.

property relations: Relations¶

Inherited from: trilium_alchemy.core.note.Note

Getter for labels, accessed as combined list or filtered by owned vs inherited.

property branches: Branches¶

Inherited from: trilium_alchemy.core.note.Note

Getter for branches, both parents (.parents) and children (.children).

property parents: ParentNotes¶

Inherited from: trilium_alchemy.core.note.Note

Getter/setter for parent notes.

Setter:: Sets set of parent notes, replacing the existing set

property children: ChildNotes¶

Inherited from: trilium_alchemy.core.note.Note

Getter/setter for child notes.

Setter:: Sets list of child notes, replacing the existing list

property content: str | bytes¶

Inherited from: trilium_alchemy.core.note.Note

Getter/setter for note content.

property content_str: str¶

Inherited from: trilium_alchemy.core.note.Note

Type-safe getter/setter for text note content.

property content_bin: bytes¶

Inherited from: trilium_alchemy.core.note.Note

Type-safe getter/setter for binary note content.

property blob_id: str¶

Inherited from: trilium_alchemy.core.note.Note

Getter for blobId, a digest of the note content.

property attachments: Attachments¶

Inherited from: trilium_alchemy.core.note.Note

Getter/setter for attachments, modeled as a list.

Setter:: Sets list of attachments, replacing the existing list. Items may be an Attachment, a pathlib.Path, or a binary file handle with a .name.

property is_string: bool¶

Inherited from: trilium_alchemy.core.note.Note

True if note as it’s currently configured has text content.

Mirrors Trilium’s src/services/utils.js:isStringNote().

property paths: list[list[Note]]¶

Inherited from: trilium_alchemy.core.note.Note

Get list of paths to this note, where each path is a list of ancestor notes.

property paths_str: list[str]¶

Inherited from: trilium_alchemy.core.note.Note

Get list of paths to this note, where each path is a string like A > B > C.

get(name: str, default: str | None = None) → str | None¶

Inherited from: trilium_alchemy.core.note.Note

Get value of first label with provided name, or None if no such label exists.

copy(deep: bool = False) → Note¶

Inherited from: trilium_alchemy.core.note.Note

Return a copy of this note, including its title, type, MIME, attributes, and content.

If deep is False, child notes are cloned to the returned copy. Otherwise, child notes are recursively deep copied.

Note

The returned copy still needs to be placed in the tree hierarchy (added as a child of another note) before Session.flush() is invoked.

sync_template(template: Note)¶

Inherited from: trilium_alchemy.core.note.Note

Update this note to match the provided template:

Set note type and MIME
Set content if empty
Recursively deep copy missing child notes, matched by title

transmute(note_cls: type[NoteT]) → NoteT¶

Inherited from: trilium_alchemy.core.note.Note

Change this note’s base to the provided class and return it.

This is useful for converting a Note instance to a subclass thereof with custom convenience APIs.

Note

Has a side effect of committing any changes to this note to Trilium.

export_zip(dest_file: pathlib.Path, export_format: Literal[html, markdown] = 'html', overwrite: bool = False)¶

Inherited from: trilium_alchemy.core.note.Note

Export this note subtree to zip file.

Parameters:

dest_file: Destination .zip file
export_format: Format of exported HTML notes
overwrite: Whether to overwrite destination path if it exists

import_zip(src_file: pathlib.Path) → Note¶

Inherited from: trilium_alchemy.core.note.Note

Import note subtree from zip file, adding the imported root as a child of this note and returning it.

Parameters:

src_file: Source .zip file

walk() → Generator[Note, None, None]¶

Inherited from: trilium_alchemy.core.note.Note

Yield this note and all children recursively.

Each note will only occur once (clones are skipped).

flush()¶

Inherited from: trilium_alchemy.core.note.Note

Flush note along with its owned attributes.

init(attributes: list[BaseAttribute], children: list[Branch], /)¶

Inherited from: trilium_alchemy.core.declarative.BaseDeclarativeMixin

Can be overridden to add attributes and/or children during instantiation. Use the following to create attribute/child with deterministic id:

BaseDeclarativeMixin.create_declarative_label
BaseDeclarativeMixin.create_declarative_relation
BaseDeclarativeMixin.create_declarative_child

Note

User should not invoke super().init(). To add attributes and children in an intuitive order, TriliumAlchemy manually traverses a BaseDeclarativeNote subclass’s MRO and invokes decorator-patched inits followed by BaseDeclarativeMixin.init.

Parameters:

attributes: List of attributes to which user can append using BaseDeclarativeMixin.create_declarative_label or BaseDeclarativeMixin.create_declarative_relation
children: List of children to which user can append using BaseDeclarativeMixin.create_declarative_child

create_declarative_label(name: str, value: str = '', inheritable: bool = False) → Label¶

Inherited from: trilium_alchemy.core.declarative.BaseDeclarativeMixin

Create and return a Label with deterministic attribute_id based on its name and note’s note_id. Should be used in subclassed BaseDeclarativeNote.init or BaseDeclarativeMixin.init to generate the same attribute_id upon every instantiation.

Multiple attributes of the same name are supported.

create_declarative_relation(name: str, target: Note, inheritable: bool = False) → Relation¶

Inherited from: trilium_alchemy.core.declarative.BaseDeclarativeMixin

Create and return a Relation with deterministic attribute_id based on its name and note’s note_id. Should be used in subclassed BaseDeclarativeNote.init or BaseDeclarativeMixin.init to generate the same attribute_id upon every instantiation.

Multiple attributes of the same name are supported.

Inherited from: trilium_alchemy.core.declarative.BaseDeclarativeMixin

Creates a child BaseDeclarativeNote with deterministic note_id and returns a Branch. Should be used in subclassed BaseDeclarativeNote.init or BaseDeclarativeMixin.init to generate the same child note_id upon every instantiation.

If the parent note’s note_id set, the child note will be assigned one so as to create the same note_id upon every instantiation.

If the child’s note_id is not fixed, a new note will be created upon every instantiation. This is the case for non-singleton subclasses.

Params following child_cls are passed to the Note and Branch initializers.

Parameters:

child_cls: Class of child to instantiate

class trilium_alchemy.core.declarative.BaseDeclarativeMixin(session: Session)¶

Bases:

abc.ABC
trilium_alchemy.core.session.SessionContainer

Aliases:

trilium_alchemy.BaseDeclarativeMixin
trilium_alchemy.core.BaseDeclarativeMixin

Reusable collection of attributes and children which can be inherited by a BaseDeclarativeNote.

icon: str | None¶

None

If provided, adds #iconClass label unless it is already present.

init(attributes: list[BaseAttribute], children: list[Branch], /)¶

Can be overridden to add attributes and/or children during instantiation. Use the following to create attribute/child with deterministic id:

BaseDeclarativeMixin.create_declarative_label
BaseDeclarativeMixin.create_declarative_relation
BaseDeclarativeMixin.create_declarative_child

Note

Parameters:

attributes: List of attributes to which user can append using BaseDeclarativeMixin.create_declarative_label or BaseDeclarativeMixin.create_declarative_relation
children: List of children to which user can append using BaseDeclarativeMixin.create_declarative_child

create_declarative_label(name: str, value: str = '', inheritable: bool = False) → Label¶

Multiple attributes of the same name are supported.

create_declarative_relation(name: str, target: Note, inheritable: bool = False) → Relation¶

Multiple attributes of the same name are supported.

If the parent note’s note_id set, the child note will be assigned one so as to create the same note_id upon every instantiation.

If the child’s note_id is not fixed, a new note will be created upon every instantiation. This is the case for non-singleton subclasses.

Params following child_cls are passed to the Note and Branch initializers.

Parameters:

child_cls: Class of child to instantiate

trilium_alchemy.core.declarative.label(name: str, value: str = '', inheritable: bool = False, accumulate: bool = False)¶

Aliases:

trilium_alchemy.label
trilium_alchemy.core.label

Adds a Label to a BaseDeclarativeNote or BaseDeclarativeMixin subclass.

Example:

@label("sorted")
class MyNote(BaseDeclarativeNote): pass

Parameters:

name: Label name
value: Label value, or empty string
inheritable: Whether label should be inherited to children
accumulate: Whether label should be added if an attribute with this name already exists from a subclassed BaseDeclarativeNote or BaseDeclarativeMixin

trilium_alchemy.core.declarative.relation(name: str, target_cls: type[BaseDeclarativeNote], inheritable: bool = False, accumulate: bool = False)¶

Aliases:

trilium_alchemy.relation
trilium_alchemy.core.relation

Adds a Relation to a BaseDeclarativeNote or BaseDeclarativeMixin subclass.

Example:

# define a task template
@label("task")
class Task(BaseTemplateNote):
    icon = "bx bx-task"

# define a note with ~template=Task
@relation("template", Task)
class TaskNote(BaseDeclarativeNote): pass

# create a task
task = TaskNote()

assert task["template"] is Task()
assert task["template"]["iconClass"] == "bx bx-task"

Parameters:

name: Relation name
target_cls: Class of relation target, will be instantiated when this note is instantiated (so it must have BaseDeclarativeNote.singleton, BaseDeclarativeNote.note_id_, or BaseDeclarativeNote.note_id_seed set)
inheritable: Whether relation should be inherited to children
accumulate: Whether relation should be added if an attribute with this name already exists from a subclassed BaseDeclarativeNote or BaseDeclarativeMixin

trilium_alchemy.core.declarative.label_def(name: str, promoted: bool = True, multi: bool = False, value_type: Literal[text, number, boolean, date, datetime, url] = 'text', inheritable: bool = False, accumulate: bool = False)¶

Aliases:

trilium_alchemy.label_def
trilium_alchemy.core.label_def

Adds a Label definition (promoted label) to a BaseDeclarativeNote or BaseDeclarativeMixin subclass.

Example:

@label("task")
@label_def("priority", value_type="number")
class Task(Template):
    icon = "bx bx-task"

Parameters:

name: Label name
promoted: Show in UI
multi: Allow multiple labels with this name in UI
value_type: Type of label value
inheritable: Whether label should be inherited to children
accumulate: Whether label should be added if an attribute with this name already exists from a subclassed BaseDeclarativeNote or BaseDeclarativeMixin

trilium_alchemy.core.declarative.relation_def(name: str, promoted: bool = True, multi: bool = False, inverse: str | None = None, inheritable: bool = False, accumulate: bool = False)¶

Aliases:

trilium_alchemy.relation_def
trilium_alchemy.core.relation_def

Adds a Relation definition (promoted relation) to a BaseDeclarativeNote or BaseDeclarativeMixin subclass.

Example:

@label("task")
@label_def("priority", value_type="number")
@relation_def("project", inheritable=True)
class Task(Template):
    icon = "bx bx-task"

Parameters:

name: Relation name
promoted: Show in UI
multi: Allow multiple relations with this name in UI
inverse: Inverse relation, e.g. if name = "isParentOf" this could be "isChildOf"
inheritable: Whether relation should be inherited to children
accumulate: Whether relation should be added if an attribute with this name already exists from a subclassed BaseDeclarativeNote or BaseDeclarativeMixin

trilium_alchemy.core.declarative.children(*children: type[BaseDeclarativeNote] | tuple[type[BaseDeclarativeNote], str])¶

Aliases:

trilium_alchemy.children
trilium_alchemy.core.children

Add BaseDeclarativeNote subclasses as children, implicitly creating a Branch. May use a tuple of (child_cls, prefix) to additionally set branch prefix.

Example:

class Child1(BaseDeclarativeNote):
    pass

class Child2(BaseDeclarativeNote):
    pass

@children(
    Child1,
    (Child2, "My prefix"),
)
class Parent(BaseDeclarativeNote):
    pass

Parameters:

children: Classes to add as children

trilium_alchemy.core.declarative.child(child: type[BaseDeclarativeNote], prefix: str = '', expanded: bool | None = None)¶

Aliases:

trilium_alchemy.child
trilium_alchemy.core.child

Instantiate provided class and add as child, creating a Branch and setting provided kwargs.

Example:

class Child(BaseDeclarativeNote):
    pass

@child(Child, prefix="My prefix")
class Parent(BaseDeclarativeNote):
    pass

Parameters:

child: Subclass of BaseDeclarativeNote
prefix: Branch specific title prefix for child note
expanded: True if child note (as a folder) appears expanded in UI; None{l=python} to preserve existing value

trilium_alchemy.core.declarative¶

Class index¶

Function index¶

Symbols¶

`trilium_alchemy.core.declarative`¶