notes

notes#

Description#

This plugin provides the ability to manage local notes on the filesystem.

Specify the directory where the notes are stored in the path parameter.

It can be synchronized with external notes plugins through the sync_to_plugins configuration parameter, which allows you to synchronize notes with other plugins that support the same API.

Configuration#

notes:
  # [Required]
  # The directory where the notes are stored.
  path:   # type=str

  # [Optional]
  # The file extension for the notes. Defaults to ``md``.
  # file_extension: md  # type=str

  # [Optional]
  # Poll interval in seconds to check for updates (default: 300).
  # If set to zero or null, the plugin will not poll for updates,
  # and events will be generated only when you manually call `BaseNotePlugin.sync <https://docs.platypush.tech/platypush/plugins/notes._base.html#platypush.plugins.notes._base.BaseNotePlugin.sync>`_.
  # poll_interval: 10.0  # type=float

  # [Optional]
  # Timeout in seconds for the plugin operations (default: 60).
  # timeout: 60  # type=int | None

  # [Optional]
  # If the API used by the plugin doesn't support
  # free-text search (that's currently the case for
  # `NextcloudNotesPlugin <https://docs.platypush.tech/platypush/plugins/nextcloud.notes.html#platypush.plugins.nextcloud.notes.NextcloudNotesPlugin>`_ and
  # for any notes plugins that use the local file system as a backend),
  # then the plugin will use a search index to perform searches. This
  # parameter specifies the maximum length of the search tokens that will
  # be indexed, where each token is composed of a sequence of
  # alphanumeric characters (including underscores). The longer the number,
  # the more tokens will be indexed and longer exact phrases will be stored,
  # but more disk space will be used for the search index (default: 4).
  # max_tokens_length: 4  # type=int

  # [Optional]
  # How long we should wait for any running
  # threads/processes to stop before exiting (default: 5 seconds).
  # stop_timeout: 5  # type=float | None

  # [Optional]
  # If set to True then the plugin will not monitor
  # for new events. This is useful if you want to run a plugin in
  # stateless mode and only leverage its actions, without triggering any
  # events. Defaults to False.
  # disable_monitor: False  # type=bool

Triggered events#

Actions#

Module reference#

class platypush.plugins.notes.ApiSettings(supports_notes_limit: bool = False, supports_notes_offset: bool = False, supports_collections_limit: bool = False, supports_collections_offset: bool = False, supports_search_limit: bool = False, supports_search_offset: bool = False, supports_search: bool = False)[source]#

Bases: object

Represents plugin-specific API settings.

__init__(supports_notes_limit: bool = False, supports_notes_offset: bool = False, supports_collections_limit: bool = False, supports_collections_offset: bool = False, supports_search_limit: bool = False, supports_search_offset: bool = False, supports_search: bool = False) → None#
class platypush.plugins.notes.BaseNotePlugin(*args, poll_interval: float = 300, timeout: int | None = 60, max_tokens_length: int = 4, **kwargs)[source]#

Bases: RunnablePlugin, DbMixin, ABC

Base class for note-taking plugins.

__init__(*args, poll_interval: float = 300, timeout: int | None = 60, max_tokens_length: int = 4, **kwargs)[source]#
Parameters:

  • poll_interval – Poll interval in seconds to check for updates (default: 300). If set to zero or null, the plugin will not poll for updates, and events will be generated only when you manually call sync().

  • timeout – Timeout in seconds for the plugin operations (default: 60).

  • max_tokens_length – If the API used by the plugin doesn’t support free-text search (that’s currently the case for platypush.plugins.nextcloud.notes.NextcloudNotesPlugin and for any notes plugins that use the local file system as a backend), then the plugin will use a search index to perform searches. This parameter specifies the maximum length of the search tokens that will be indexed, where each token is composed of a sequence of alphanumeric characters (including underscores). The longer the number, the more tokens will be indexed and longer exact phrases will be stored, but more disk space will be used for the search index (default: 4).

create_collection(title: str, *args, description: str | None = None, parent: Any | None = None, **kwargs) → dict[source]#

Create a new note collection with the specified title and description.

Parameters:

  • title – The title of the new collection.

  • description – Optional description for the new collection.

  • parent – Optional parent collection ID to create a sub-collection.

Returns:

The created collection as a dictionary, format:

{
  "collections": [
    {
      "description": "Notes related to work projects",
      "id": 1235,
      "title": "Work Notes"
    }
  ],
  "created_at": "2020-01-01T00:00:00+00:00",
  "description": "A collection of my important notes",
  "id": 1234,
  "notes": [
    {
      "content": "Note content goes here",
      "created_at": "2023-10-01T12:00:00Z",
      "id": 2345,
      "title": "My Important Note",
      "updated_at": "2023-10-02T12:00:00Z"
    }
  ],
  "parent": {
    "description": "A top-level collection of all notes",
    "id": 1233,
    "title": "All Notes"
  },
  "title": "My Notes",
  "updated_at": "2020-01-01T00:00:00+00:00"
}

create_note(title: str, content: str, *args, description: str | None = None, collection: Any | None = None, geo: Dict[str, float | None] | None = None, source: dict | None = None, author: str | None = None, **kwargs) → dict[source]#

Create a new note with the specified title and content.

Parameters:

  • title – The title of the new note.

  • content – The content of the new note.

  • description – Optional description for the note.

  • collection – Optional collection ID to add the note to.

  • geo – Optional geographical coordinates as a dictionary with the fields latitude, longitude, and altitude.

  • source – Optional source information for the note, with at least one of the fields url, name or app. By default, the source is platypush and the app is tech.platypush.

  • author – Optional author of the note.

Returns:

The created note as a dictionary, format:

{
  "altitude": 30.0,
  "author": "John Doe",
  "content": "Note content goes here",
  "created_at": "2020-01-01T00:00:00+00:00",
  "description": "This note contains important information.",
  "digest": "abc123def456",
  "id": 2345,
  "latitude": 37.7749,
  "longitude": -122.4194,
  "parent": {
    "description": "A collection of my important notes",
    "id": 1234,
    "title": "My Notes"
  },
  "source": {
    "app": "My Note App",
    "name": "My Note Source",
    "url": "https://example.com/note"
  },
  "tags": [
    "important",
    "work"
  ],
  "title": "My Important Note",
  "updated_at": "2020-01-01T00:00:00+00:00"
}

delete_collection(collection_id: Any, *args, **kwargs)[source]#

Delete a note collection by ID.

Parameters:

collection_id – The ID of the collection to delete.

delete_note(note_id: Any, *args, **kwargs)[source]#

Delete a note by ID.

Parameters:

note_id – The ID of the note to delete.

edit_collection(collection_id: Any, *args, title: str | None = None, description: str | None = None, parent: Any | None = None, **kwargs) → dict[source]#

Edit an existing note collection by ID.

Parameters:

  • collection_id – The ID of the collection to edit.

  • title – New title for the collection.

  • description – New description for the collection.

  • parent – New parent collection ID to move the collection under.

Returns:

The updated collection as a dictionary, format:

{
  "collections": [
    {
      "description": "Notes related to work projects",
      "id": 1235,
      "title": "Work Notes"
    }
  ],
  "created_at": "2020-01-01T00:00:00+00:00",
  "description": "A collection of my important notes",
  "id": 1234,
  "notes": [
    {
      "content": "Note content goes here",
      "created_at": "2023-10-01T12:00:00Z",
      "id": 2345,
      "title": "My Important Note",
      "updated_at": "2023-10-02T12:00:00Z"
    }
  ],
  "parent": {
    "description": "A top-level collection of all notes",
    "id": 1233,
    "title": "All Notes"
  },
  "title": "My Notes",
  "updated_at": "2020-01-01T00:00:00+00:00"
}

edit_note(note_id: Any, *args, title: str | None = None, content: str | None = None, description: str | None = None, collection: Any | None = None, geo: Dict[str, float | None] | None = None, source: dict | None = None, author: str | None = None, **kwargs) → dict[source]#

Edit an existing note by ID.

Parameters:

  • note_id – The ID of the note to edit.

  • title – New title for the note.

  • content – New content for the note.

  • description – Optional new description for the note.

  • collection – New collection ID to move the note under.

  • geo – Optional geographical coordinates as a dictionary with the fields latitude, longitude, and altitude.

  • source – Optional source information for the note, with at least one of the fields url, name or app.

  • author – Optional author of the note.

Returns:

The updated note as a dictionary, format:

{
  "altitude": 30.0,
  "author": "John Doe",
  "content": "Note content goes here",
  "created_at": "2020-01-01T00:00:00+00:00",
  "description": "This note contains important information.",
  "digest": "abc123def456",
  "id": 2345,
  "latitude": 37.7749,
  "longitude": -122.4194,
  "parent": {
    "description": "A collection of my important notes",
    "id": 1234,
    "title": "My Notes"
  },
  "source": {
    "app": "My Note App",
    "name": "My Note Source",
    "url": "https://example.com/note"
  },
  "tags": [
    "important",
    "work"
  ],
  "title": "My Important Note",
  "updated_at": "2020-01-01T00:00:00+00:00"
}

classmethod extract_search_terms(query: str) → List[str]#

Extract search terms from the query string.

get_collection(collection_id: Any, *args, **kwargs) → dict[source]#

Get a single note collection by ID.

Parameters:

collection_id – The ID of the collection to retrieve.

Returns:

The collection as a dictionary, format:

{
  "collections": [
    {
      "description": "Notes related to work projects",
      "id": 1235,
      "title": "Work Notes"
    }
  ],
  "created_at": "2020-01-01T00:00:00+00:00",
  "description": "A collection of my important notes",
  "id": 1234,
  "notes": [
    {
      "content": "Note content goes here",
      "created_at": "2023-10-01T12:00:00Z",
      "id": 2345,
      "title": "My Important Note",
      "updated_at": "2023-10-02T12:00:00Z"
    }
  ],
  "parent": {
    "description": "A top-level collection of all notes",
    "id": 1233,
    "title": "All Notes"
  },
  "title": "My Notes",
  "updated_at": "2020-01-01T00:00:00+00:00"
}

get_collections(*args, limit: int | None = None, offset: int | None = 0, sort: Dict[str, bool] | None = None, filter: Dict[str, Any] | None = None, fetch: bool = False, **kwargs) → Iterable[dict][source]#

Get note collections from the cache or fetch them from the backend.

Parameters:

  • limit – Maximum number of collections to retrieve (default: None, meaning no limit).

  • offset – Offset to start retrieving collections from (default: 0).

  • sort – A dictionary specifying the fields to sort by and their order. Example: {‘created_at’: True} sorts by creation date in ascending order, while {‘created_at’: False} sorts in descending order.

  • filter – A dictionary specifying filters to apply to the collections, in the form of a dictionary where the keys are field names and the values are regular expressions to match against the field values.

  • fetch – If True, always fetch the latest collections from the backend, regardless of the cache state (default: False).

  • kwargs – Additional keyword arguments to pass to the fetch method.

Returns:

An iterable of note collections, format:

[
  {
    "collections": [
      {
        "description": "Notes related to work projects",
        "id": 1235,
        "title": "Work Notes"
      }
    ],
    "created_at": "2020-01-01T00:00:00+00:00",
    "description": "A collection of my important notes",
    "id": 1234,
    "notes": [
      {
        "content": "Note content goes here",
        "created_at": "2023-10-01T12:00:00Z",
        "id": 2345,
        "title": "My Important Note",
        "updated_at": "2023-10-02T12:00:00Z"
      }
    ],
    "parent": {
      "description": "A top-level collection of all notes",
      "id": 1233,
      "title": "All Notes"
    },
    "title": "My Notes",
    "updated_at": "2020-01-01T00:00:00+00:00"
  }
]

get_note(note_id: Any, *args, **kwargs) → dict[source]#

Get a single note and its full content by ID.

Parameters:

note_id – The ID of the note to retrieve.

Returns:

The note as a dictionary, format:

{
  "altitude": 30.0,
  "author": "John Doe",
  "content": "Note content goes here",
  "created_at": "2020-01-01T00:00:00+00:00",
  "description": "This note contains important information.",
  "digest": "abc123def456",
  "id": 2345,
  "latitude": 37.7749,
  "longitude": -122.4194,
  "parent": {
    "description": "A collection of my important notes",
    "id": 1234,
    "title": "My Notes"
  },
  "source": {
    "app": "My Note App",
    "name": "My Note Source",
    "url": "https://example.com/note"
  },
  "tags": [
    "important",
    "work"
  ],
  "title": "My Important Note",
  "updated_at": "2020-01-01T00:00:00+00:00"
}

get_notes(*args, limit: int | None = None, offset: int | None = 0, sort: Dict[str, bool] | None = None, filter: Dict[str, Any] | None = None, fetch: bool = False, **kwargs) → Iterable[dict][source]#

Get notes from the cache or fetch them from the backend.

Parameters:

  • limit – Maximum number of collections to retrieve (default: None, meaning no limit).

  • offset – Offset to start retrieving collections from (default: 0).

  • sort – A dictionary specifying the fields to sort by and their order. Example: {‘created_at’: True} sorts by creation date in ascending order, while {‘created_at’: False} sorts in descending order.

  • filter – A dictionary specifying filters to apply to the notes, in the form of a dictionary where the keys are field names and the values are regular expressions to match against the field values.

  • fetch – If True, always fetch the latest collections from the backend, regardless of the cache state (default: False).

  • kwargs – Additional keyword arguments to pass to the fetch method.

Returns:

An iterable of notes, format:

[
  {
    "altitude": 30.0,
    "author": "John Doe",
    "content": "Note content goes here",
    "created_at": "2020-01-01T00:00:00+00:00",
    "description": "This note contains important information.",
    "digest": "abc123def456",
    "id": 2345,
    "latitude": 37.7749,
    "longitude": -122.4194,
    "parent": {
      "description": "A collection of my important notes",
      "id": 1234,
      "title": "My Notes"
    },
    "source": {
      "app": "My Note App",
      "name": "My Note Source",
      "url": "https://example.com/note"
    },
    "tags": [
      "important",
      "work"
    ],
    "title": "My Important Note",
    "updated_at": "2020-01-01T00:00:00+00:00"
  }
]

reset_sync()[source]#

Reset the sync state.

  1. Reset the last sync time to None, forcing a full resync on the next call to sync(), which in turn will re-trigger all notes and collections events.

  2. Clear the local notes and collections cache.

search(*args, query: str, type: str = 'note', include_terms: Dict[str, Any] | None = None, exclude_terms: Dict[str, Any] | None = None, created_before: datetime | None = None, created_after: datetime | None = None, updated_before: datetime | None = None, updated_after: datetime | None = None, limit: int | None = None, offset: int | None = 0, **kwargs)[source]#

Search for notes or collections based on the provided query and filters.

In most of the cases (but it depends on the backend) double-quoted search terms will match exact phrases, while unquoted queries will match any of the words in the query.

Wildcards (again, depending on the backend) in the search terms are also supported.

Parameters:

  • query – The search query string (it will be searched in all the fields).

  • type – The type of items to search for - note, collection, or tag (default: note).

  • include_terms – Optional dictionary of terms to include in the search. The keys are field names and the values are strings to match against.

  • exclude_terms – Optional dictionary of terms to exclude from the search. The keys are field names and the values are strings to exclude from the results.

  • created_before – Optional datetime ISO string or UNIX timestamp to filter items created before this date.

  • created_after – Optional datetime ISO string or UNIX timestamp to filter items created after this date.

  • updated_before – Optional datetime ISO string or UNIX timestamp to filter items updated before this date.

  • updated_after – Optional datetime ISO string or UNIX timestamp to filter items updated after this date.

  • limit – Maximum number of items to retrieve (default: None, meaning no limit, or depending on the default limit of the backend).

  • offset – Offset to start retrieving items from (default: 0).

Returns:

An iterable of matching items, format:

{
    "has_more": false
    "results" [
        {
            "type": "note",
            "item": {
                "id": "note-id",
                "title": "Note Title",
                "content": "Note content...",
                "created_at": "2023-10-01T12:00:00Z",
                "updated_at": "2023-10-01T12:00:00Z",
                // ...
            }
        }
    ]
}

sync(*args, **kwargs)[source]#

Synchronize the notes and collections with the backend. This method is called periodically based on the poll_interval setting. If poll_interval is zero or null, you can manually call this method to synchronize the notes and collections.

tokenize(content: str) → List[SearchToken]#

Tokenize the content into search tokens.

class platypush.plugins.notes.Item(type: ItemType, item: Storable)[source]#

Bases: Serializable

Represents a generic note item.

__init__(type: ItemType, item: Storable) → None#
to_dict() → Dict[str, Any][source]#

Convert the item to a dictionary representation.

class platypush.plugins.notes.ItemType(*values)[source]#

Bases: Enum

Enum representing the type of item.

class platypush.plugins.notes.Note(id: Any, plugin: str, title: str, description: str | None = None, content: str | None = None, parent: NoteCollection | None = None, tags: Set[str] = <factory>, created_at: datetime | None = None, updated_at: datetime | None = None, digest: str | None = None, latitude: float | None = None, longitude: float | None = None, altitude: float | None = None, author: str | None = None, source: NoteSource | None = None, _path: str | None = None)[source]#

Bases: Storable

Represents a note with a title and content.

__init__(id: Any, plugin: str, title: str, description: str | None = None, content: str | None = None, parent: NoteCollection | None = None, tags: Set[str] = <factory>, created_at: datetime | None = None, updated_at: datetime | None = None, digest: str | None = None, latitude: float | None = None, longitude: float | None = None, altitude: float | None = None, author: str | None = None, source: NoteSource | None = None, _path: str | None = None) → None#
to_dict() → dict[source]#

Convert the object to a dictionary representation.

class platypush.plugins.notes.NoteCollection(id: Any, plugin: str, title: str, description: str | None = None, parent: NoteCollection | None = None, created_at: datetime | None = None, updated_at: datetime | None = None, _notes: Any, ~platypush.common.notes.Note]=<factory>, _collections: Any, ~platypush.common.notes.NoteCollection]=<factory>)[source]#

Bases: Storable

Represents a collection of notes.

__init__(id: Any, plugin: str, title: str, description: str | None = None, parent: NoteCollection | None = None, created_at: datetime | None = None, updated_at: datetime | None = None, _notes: Any, ~platypush.common.notes.Note]=<factory>, _collections: Any, ~platypush.common.notes.NoteCollection]=<factory>) → None#
to_dict() → dict[source]#

Convert the object to a dictionary representation.

class platypush.plugins.notes.NoteSource(name: str | None = None, url: str | None = None, app: str | None = None)[source]#

Bases: Serializable

Represents a source for a note, such as a URL or file path.

__init__(name: str | None = None, url: str | None = None, app: str | None = None) → None#
to_dict() → dict[source]#

Convert the object to a dictionary representation.

class platypush.plugins.notes.NotesPlugin(path: str, *args, file_extension: str = 'md', poll_interval: float = 10.0, **kwargs)[source]#

Bases: BaseNotePlugin

This plugin provides the ability to manage local notes on the filesystem.

Specify the directory where the notes are stored in the path parameter.

It can be synchronized with external notes plugins through the sync_to_plugins configuration parameter, which allows you to synchronize notes with other plugins that support the same API.

__init__(path: str, *args, file_extension: str = 'md', poll_interval: float = 10.0, **kwargs)[source]#
Parameters:

  • path – The directory where the notes are stored.

  • file_extension – The file extension for the notes. Defaults to md.

create_collection(title: str, *args, description: str | None = None, parent: Any | None = None, **kwargs) → dict#

Create a new note collection with the specified title and description.

Parameters:

  • title – The title of the new collection.

  • description – Optional description for the new collection.

  • parent – Optional parent collection ID to create a sub-collection.

Returns:

The created collection as a dictionary, format:

{
  "collections": [
    {
      "description": "Notes related to work projects",
      "id": 1235,
      "title": "Work Notes"
    }
  ],
  "created_at": "2020-01-01T00:00:00+00:00",
  "description": "A collection of my important notes",
  "id": 1234,
  "notes": [
    {
      "content": "Note content goes here",
      "created_at": "2023-10-01T12:00:00Z",
      "id": 2345,
      "title": "My Important Note",
      "updated_at": "2023-10-02T12:00:00Z"
    }
  ],
  "parent": {
    "description": "A top-level collection of all notes",
    "id": 1233,
    "title": "All Notes"
  },
  "title": "My Notes",
  "updated_at": "2020-01-01T00:00:00+00:00"
}

create_note(title: str, content: str, *args, description: str | None = None, collection: Any | None = None, geo: Dict[str, float | None] | None = None, source: dict | None = None, author: str | None = None, **kwargs) → dict#

Create a new note with the specified title and content.

Parameters:

  • title – The title of the new note.

  • content – The content of the new note.

  • description – Optional description for the note.

  • collection – Optional collection ID to add the note to.

  • geo – Optional geographical coordinates as a dictionary with the fields latitude, longitude, and altitude.

  • source – Optional source information for the note, with at least one of the fields url, name or app. By default, the source is platypush and the app is tech.platypush.

  • author – Optional author of the note.

Returns:

The created note as a dictionary, format:

{
  "altitude": 30.0,
  "author": "John Doe",
  "content": "Note content goes here",
  "created_at": "2020-01-01T00:00:00+00:00",
  "description": "This note contains important information.",
  "digest": "abc123def456",
  "id": 2345,
  "latitude": 37.7749,
  "longitude": -122.4194,
  "parent": {
    "description": "A collection of my important notes",
    "id": 1234,
    "title": "My Notes"
  },
  "source": {
    "app": "My Note App",
    "name": "My Note Source",
    "url": "https://example.com/note"
  },
  "tags": [
    "important",
    "work"
  ],
  "title": "My Important Note",
  "updated_at": "2020-01-01T00:00:00+00:00"
}

delete_collection(collection_id: Any, *args, **kwargs)#

Delete a note collection by ID.

Parameters:

collection_id – The ID of the collection to delete.

delete_note(note_id: Any, *args, **kwargs)#

Delete a note by ID.

Parameters:

note_id – The ID of the note to delete.

edit_collection(collection_id: Any, *args, title: str | None = None, description: str | None = None, parent: Any | None = None, **kwargs) → dict#

Edit an existing note collection by ID.

Parameters:

  • collection_id – The ID of the collection to edit.

  • title – New title for the collection.

  • description – New description for the collection.

  • parent – New parent collection ID to move the collection under.

Returns:

The updated collection as a dictionary, format:

{
  "collections": [
    {
      "description": "Notes related to work projects",
      "id": 1235,
      "title": "Work Notes"
    }
  ],
  "created_at": "2020-01-01T00:00:00+00:00",
  "description": "A collection of my important notes",
  "id": 1234,
  "notes": [
    {
      "content": "Note content goes here",
      "created_at": "2023-10-01T12:00:00Z",
      "id": 2345,
      "title": "My Important Note",
      "updated_at": "2023-10-02T12:00:00Z"
    }
  ],
  "parent": {
    "description": "A top-level collection of all notes",
    "id": 1233,
    "title": "All Notes"
  },
  "title": "My Notes",
  "updated_at": "2020-01-01T00:00:00+00:00"
}

edit_note(note_id: Any, *args, title: str | None = None, content: str | None = None, description: str | None = None, collection: Any | None = None, geo: Dict[str, float | None] | None = None, source: dict | None = None, author: str | None = None, **kwargs) → dict#

Edit an existing note by ID.

Parameters:

  • note_id – The ID of the note to edit.

  • title – New title for the note.

  • content – New content for the note.

  • description – Optional new description for the note.

  • collection – New collection ID to move the note under.

  • geo – Optional geographical coordinates as a dictionary with the fields latitude, longitude, and altitude.

  • source – Optional source information for the note, with at least one of the fields url, name or app.

  • author – Optional author of the note.

Returns:

The updated note as a dictionary, format:

{
  "altitude": 30.0,
  "author": "John Doe",
  "content": "Note content goes here",
  "created_at": "2020-01-01T00:00:00+00:00",
  "description": "This note contains important information.",
  "digest": "abc123def456",
  "id": 2345,
  "latitude": 37.7749,
  "longitude": -122.4194,
  "parent": {
    "description": "A collection of my important notes",
    "id": 1234,
    "title": "My Notes"
  },
  "source": {
    "app": "My Note App",
    "name": "My Note Source",
    "url": "https://example.com/note"
  },
  "tags": [
    "important",
    "work"
  ],
  "title": "My Important Note",
  "updated_at": "2020-01-01T00:00:00+00:00"
}

classmethod extract_search_terms(query: str) → List[str]#

Extract search terms from the query string.

get_collection(collection_id: Any, *args, **kwargs) → dict#

Get a single note collection by ID.

Parameters:

collection_id – The ID of the collection to retrieve.

Returns:

The collection as a dictionary, format:

{
  "collections": [
    {
      "description": "Notes related to work projects",
      "id": 1235,
      "title": "Work Notes"
    }
  ],
  "created_at": "2020-01-01T00:00:00+00:00",
  "description": "A collection of my important notes",
  "id": 1234,
  "notes": [
    {
      "content": "Note content goes here",
      "created_at": "2023-10-01T12:00:00Z",
      "id": 2345,
      "title": "My Important Note",
      "updated_at": "2023-10-02T12:00:00Z"
    }
  ],
  "parent": {
    "description": "A top-level collection of all notes",
    "id": 1233,
    "title": "All Notes"
  },
  "title": "My Notes",
  "updated_at": "2020-01-01T00:00:00+00:00"
}

get_collections(*args, limit: int | None = None, offset: int | None = 0, sort: Dict[str, bool] | None = None, filter: Dict[str, Any] | None = None, fetch: bool = False, **kwargs) → Iterable[dict]#

Get note collections from the cache or fetch them from the backend.

Parameters:

  • limit – Maximum number of collections to retrieve (default: None, meaning no limit).

  • offset – Offset to start retrieving collections from (default: 0).

  • sort – A dictionary specifying the fields to sort by and their order. Example: {‘created_at’: True} sorts by creation date in ascending order, while {‘created_at’: False} sorts in descending order.

  • filter – A dictionary specifying filters to apply to the collections, in the form of a dictionary where the keys are field names and the values are regular expressions to match against the field values.

  • fetch – If True, always fetch the latest collections from the backend, regardless of the cache state (default: False).

  • kwargs – Additional keyword arguments to pass to the fetch method.

Returns:

An iterable of note collections, format:

[
  {
    "collections": [
      {
        "description": "Notes related to work projects",
        "id": 1235,
        "title": "Work Notes"
      }
    ],
    "created_at": "2020-01-01T00:00:00+00:00",
    "description": "A collection of my important notes",
    "id": 1234,
    "notes": [
      {
        "content": "Note content goes here",
        "created_at": "2023-10-01T12:00:00Z",
        "id": 2345,
        "title": "My Important Note",
        "updated_at": "2023-10-02T12:00:00Z"
      }
    ],
    "parent": {
      "description": "A top-level collection of all notes",
      "id": 1233,
      "title": "All Notes"
    },
    "title": "My Notes",
    "updated_at": "2020-01-01T00:00:00+00:00"
  }
]

get_note(note_id: Any, *args, **kwargs) → dict#

Get a single note and its full content by ID.

Parameters:

note_id – The ID of the note to retrieve.

Returns:

The note as a dictionary, format:

{
  "altitude": 30.0,
  "author": "John Doe",
  "content": "Note content goes here",
  "created_at": "2020-01-01T00:00:00+00:00",
  "description": "This note contains important information.",
  "digest": "abc123def456",
  "id": 2345,
  "latitude": 37.7749,
  "longitude": -122.4194,
  "parent": {
    "description": "A collection of my important notes",
    "id": 1234,
    "title": "My Notes"
  },
  "source": {
    "app": "My Note App",
    "name": "My Note Source",
    "url": "https://example.com/note"
  },
  "tags": [
    "important",
    "work"
  ],
  "title": "My Important Note",
  "updated_at": "2020-01-01T00:00:00+00:00"
}

get_notes(*args, limit: int | None = None, offset: int | None = 0, sort: Dict[str, bool] | None = None, filter: Dict[str, Any] | None = None, fetch: bool = False, **kwargs) → Iterable[dict]#

Get notes from the cache or fetch them from the backend.

Parameters:

  • limit – Maximum number of collections to retrieve (default: None, meaning no limit).

  • offset – Offset to start retrieving collections from (default: 0).

  • sort – A dictionary specifying the fields to sort by and their order. Example: {‘created_at’: True} sorts by creation date in ascending order, while {‘created_at’: False} sorts in descending order.

  • filter – A dictionary specifying filters to apply to the notes, in the form of a dictionary where the keys are field names and the values are regular expressions to match against the field values.

  • fetch – If True, always fetch the latest collections from the backend, regardless of the cache state (default: False).

  • kwargs – Additional keyword arguments to pass to the fetch method.

Returns:

An iterable of notes, format:

[
  {
    "altitude": 30.0,
    "author": "John Doe",
    "content": "Note content goes here",
    "created_at": "2020-01-01T00:00:00+00:00",
    "description": "This note contains important information.",
    "digest": "abc123def456",
    "id": 2345,
    "latitude": 37.7749,
    "longitude": -122.4194,
    "parent": {
      "description": "A collection of my important notes",
      "id": 1234,
      "title": "My Notes"
    },
    "source": {
      "app": "My Note App",
      "name": "My Note Source",
      "url": "https://example.com/note"
    },
    "tags": [
      "important",
      "work"
    ],
    "title": "My Important Note",
    "updated_at": "2020-01-01T00:00:00+00:00"
  }
]

reset_sync()#

Reset the sync state.

  1. Reset the last sync time to None, forcing a full resync on the next call to sync(), which in turn will re-trigger all notes and collections events.

  2. Clear the local notes and collections cache.

search(*args, query: str, type: str = 'note', include_terms: Dict[str, Any] | None = None, exclude_terms: Dict[str, Any] | None = None, created_before: datetime | None = None, created_after: datetime | None = None, updated_before: datetime | None = None, updated_after: datetime | None = None, limit: int | None = None, offset: int | None = 0, **kwargs)#

Search for notes or collections based on the provided query and filters.

In most of the cases (but it depends on the backend) double-quoted search terms will match exact phrases, while unquoted queries will match any of the words in the query.

Wildcards (again, depending on the backend) in the search terms are also supported.

Parameters:

  • query – The search query string (it will be searched in all the fields).

  • type – The type of items to search for - note, collection, or tag (default: note).

  • include_terms – Optional dictionary of terms to include in the search. The keys are field names and the values are strings to match against.

  • exclude_terms – Optional dictionary of terms to exclude from the search. The keys are field names and the values are strings to exclude from the results.

  • created_before – Optional datetime ISO string or UNIX timestamp to filter items created before this date.

  • created_after – Optional datetime ISO string or UNIX timestamp to filter items created after this date.

  • updated_before – Optional datetime ISO string or UNIX timestamp to filter items updated before this date.

  • updated_after – Optional datetime ISO string or UNIX timestamp to filter items updated after this date.

  • limit – Maximum number of items to retrieve (default: None, meaning no limit, or depending on the default limit of the backend).

  • offset – Offset to start retrieving items from (default: 0).

Returns:

An iterable of matching items, format:

{
    "has_more": false
    "results" [
        {
            "type": "note",
            "item": {
                "id": "note-id",
                "title": "Note Title",
                "content": "Note content...",
                "created_at": "2023-10-01T12:00:00Z",
                "updated_at": "2023-10-01T12:00:00Z",
                // ...
            }
        }
    ]
}

sync(*args, **kwargs)#

Synchronize the notes and collections with the backend. This method is called periodically based on the poll_interval setting. If poll_interval is zero or null, you can manually call this method to synchronize the notes and collections.

tokenize(content: str) → List[SearchToken]#

Tokenize the content into search tokens.

class platypush.plugins.notes.Results(items: Iterable[Item] = <factory>, has_more: bool = False)[source]#

Bases: Serializable

Represents a collection of results, which can include notes, collections, and tags.

__init__(items: Iterable[Item] = <factory>, has_more: bool = False) → None#
to_dict() → Dict[str, Any][source]#

Convert the results to a dictionary representation.