Notes API

class nc_py_api.notes.Note(raw_data: dict)

Class representing one Note.

property note_id: int

Unique identifier which is created by the server.

property etag: str

The note’s entity tag (ETag) indicates if a note’s attribute has changed.

property readonly: bool

Indicates if the note is read-only.

property title: str

The note’s title is also used as filename for the note’s file.

Note

Some special characters are automatically removed and a sequential number is added if a note with the same title in the same category exists.

property content: str

Notes can contain arbitrary text.

Note

Formatting should be done using Markdown, but not every markup can be supported by every client.

property category: str

Every note is assigned to a category.

By default, the category is an empty string (not null), which means the note is uncategorized.

Note

Categories are mapped to folders in the file backend. Illegal characters are automatically removed and the respective folder is automatically created. Sub-categories (mapped to sub-folders) can be created by using / as delimiter.

property favorite: bool

If a note is marked as favorite, it is displayed at the top of the notes’ list.

property last_modified: datetime

Last modified date/time of the note.

If not provided on note creation or content update, the current time is used.

class nc_py_api.notes.NotesSettings

Settings of Notes App.

notes_path: str

Path to the folder, where note’s files are stored in Nextcloud. The path must be relative to the user folder. Default is the localized string Notes.

file_suffix: str

Newly created note’s files will have this file suffix. Default is .txt.

class nc_py_api.notes._NotesAPI(session: NcSessionBasic)

Class implementing Nextcloud Notes API.

last_etag: str

Used by get_list, when etag param is True.

property available: bool

Returns True if the Nextcloud instance supports this feature, False otherwise.

get_list(category: str | None = None, modified_since: int | None = None, limit: int | None = None, cursor: str | None = None, no_content: bool = False, etag: bool = False) → list[Note]

Get information of all Notes.

Parameters:

• category – Filter the result by category name. Notes with another category are not included in the result.

• modified_since – When provided only results newer than given Unix timestamp are returned.

• limit –

  Limit response to contain no more than the given number of notes. If there are more notes, then the result is chunked and the HTTP response header X-Notes-Chunk-Cursor is sent with a string value.

  Note

  Use response_headers property to achieve that.

• cursor – You should use the string value from the last request’s HTTP response header X-Notes-Chunk-Cursor in order to get the next chunk of notes.

• no_content – Flag indicating should content field be excluded from response.

• etag – Flag indicating should ETag from last call be used. Default = False.

by_id(note: Note) → Note

Get updated information about Note.

create(title: str, content: str | None = None, category: str | None = None, favorite: bool | None = None, last_modified: int | str | datetime | None = None) → Note

Create new Note.

update(note: Note, title: str | None = None, content: str | None = None, category: str | None = None, favorite: bool | None = None, overwrite: bool = False) → Note

Updates Note.

overwrite specifies should be or not the Note updated even if it was changed on server(has different ETag).

delete(note: int | Note) → None

Deletes a Note.

get_settings() → NotesSettings

Returns Notes App settings.

set_settings(notes_path: str | None = None, file_suffix: str | None = None) → None

Change specified setting(s).