Research Notes¶

Methods for managing research notes and replies (/api/notes).

pyclann.client.NotesClient ¶

NotesClient(http: _HttpSession)

Methods for the /api/notes resource.

list ¶

list(*, created_by: str | None = None, tree: str | None = None) -> builtins.list[ResearchNote]

Return top-level research notes (replies excluded).

Parameters:

Name	Type	Description	Default
`created_by`	`str \| None`	Filter by creator username.	`None`
`tree`	`str \| None`	Filter by tree slug.	`None`

Returns:

Type	Description
`list[ResearchNote]`	List of :class:`~pyclann.models.ResearchNote` objects.

Raises:

Type	Description
`ClannAuthError`	If not authenticated.

create ¶

create(title: str, trees: list[str], *, description: str | None = None, body: str | None = None, folder_id: str | None = None, created_by: str | None = None, is_shared: bool = False) -> ResearchNote

Create a research note.

Parameters:

Name	Type	Description	Default
`title`	`str`	Note title.	required
`trees`	`list[str]`	Tree slugs this note is linked to.	required
`description`	`str \| None`	Short description.	`None`
`body`	`str \| None`	Markdown body.	`None`
`folder_id`	`str \| None`	ID of the folder to file this note in.	`None`
`created_by`	`str \| None`	Username of the creator.	`None`
`is_shared`	`bool`	When `True`, visible to all team members with tree access.	`False`

Returns:

Type	Description
`ResearchNote`	The newly created :class:`~pyclann.models.ResearchNote`.

Raises:

Type	Description
`ClannAuthError`	If not authenticated.

get ¶

get(note_id: str) -> ResearchNote

Fetch a single research note.

Parameters:

Name	Type	Description	Default
`note_id`	`str`	Full record ID (`"research_note:01jd4a8xyz"`) or bare ULID.	required

Returns:

Type	Description
`ResearchNote`	class:`~pyclann.models.ResearchNote`.

Raises:

Type	Description
`ClannNotFoundError`	If the note does not exist.
`ClannAuthError`	If not authenticated.

update ¶

update(note_id: str, *, title: str | None = None, description: str | None = None, body: str | None = None, trees: list[str] | None = None, is_shared: bool | None = None) -> ResearchNote

Update a research note; only supplied fields are changed.

Parameters:

Name	Type	Description	Default
`note_id`	`str`	Full record ID or bare ULID.	required

Returns:

Type	Description
`ResearchNote`	The updated :class:`~pyclann.models.ResearchNote`.

Raises:

Type	Description
`ClannNotFoundError`	If the note does not exist.
`ClannAuthError`	If not authenticated.

delete ¶

delete(note_id: str) -> None

Delete a note and all its replies.

Parameters:

Name	Type	Description	Default
`note_id`	`str`	Full record ID or bare ULID.	required

Raises:

Type	Description
`ClannNotFoundError`	If the note does not exist.
`ClannAuthError`	If not authenticated.

set_folder ¶

set_folder(note_id: str, folder_id: str | None) -> ResearchNote

Move a note to a folder, or unfile it.

Parameters:

Name	Type	Description	Default
`note_id`	`str`	Full record ID or bare ULID.	required
`folder_id`	`str \| None`	ID of the destination folder, or `None` to unfile.	required

Returns:

Type	Description
`ResearchNote`	The updated :class:`~pyclann.models.ResearchNote`.

Raises:

Type	Description
`ClannNotFoundError`	If the note does not exist.
`ClannAuthError`	If not authenticated.

list_replies ¶

list_replies(note_id: str) -> builtins.list[ResearchNote]

Return all replies to a note, ordered by creation time.

Parameters:

Name	Type	Description	Default
`note_id`	`str`	Full record ID or bare ULID of the parent note.	required

Returns:

Type	Description
`list[ResearchNote]`	List of reply :class:`~pyclann.models.ResearchNote` objects.

Raises:

Type	Description
`ClannNotFoundError`	If the note does not exist.
`ClannAuthError`	If not authenticated.

create_reply ¶

create_reply(note_id: str, body: str, *, created_by: str | None = None, trees: list[str] | None = None) -> ResearchNote

Post a reply to a shared note.

Parameters:

Name	Type	Description	Default
`note_id`	`str`	Full record ID or bare ULID of the parent note.	required
`body`	`str`	Reply text (Markdown supported).	required
`created_by`	`str \| None`	Username of the reply author.	`None`
`trees`	`list[str] \| None`	Tree slugs to link the reply to (defaults to empty list).	`None`

Returns:

Type	Description
`ResearchNote`	The created reply :class:`~pyclann.models.ResearchNote`.

Raises:

Type	Description
`ClannNotFoundError`	If the note does not exist.
`ClannValidationError`	If the note is private (`is_shared == False`).
`ClannAuthError`	If not authenticated.