Server API

Warning

Please know that the API is not stable at this time. API changes, additions and removals are only documented in the release changelogs, so make sure to read them. Things should stabilize once HPX enters beta status.

Summary

Meta

add_items_to_metadata_queue([items_kind, …])

Add items to the metadata queue

add_urls_to_download_queue([urls, …])

Add a list of urls to the download queue

check_update([push])

Check for new release

clear_queue([queue_type])

Clear a queue

get_changelog()

Get the changelog in markdown formatted text The changelog returned is for the current release or a new update

get_command_progress([command_ids])

Get progress of command operation

get_command_state(command_ids)

Get state of command

get_command_value(command_ids[, raise_error])

Get the returned command value

get_download_info()

Get a list of download handlers

get_locales()

Retrieve available translation locales

get_log([log_type])

Get log

get_login_info([identifier])

Get a list of logins

get_metadata_info()

Get a list of metadata handlers

get_notifications()

Pull unread notifications

get_properties()

Get various server properties

get_queue_items([limit, queue_type])

Get current items in a queue

get_queue_state([queue_type, include_finished])

Get current state of a queue

get_version()

Get version of components: ‘core’, ‘db’ and ‘torrent’

mark_notification_read(ids)

Mark and unread notification as read

reindex([limit])

Reindex datebase items

remove_item_from_queue([item_id, item_type, …])

Add an item to a queue

restart_application([delay])

Restart the application

shutdown_application([delay])

Shutdown the application

start_command(command_ids)

Start running a command

start_queue([queue_type])

Start a queue

stop_command(command_ids)

Stop command from running

stop_queue([queue_type])

Stop a queue

submit_login(identifier, credentials[, options])

Submit login credentials

sweep_trash([options, force])

Sweep trashed items

update_application([download_url, restart])

Update the application with a new release.

UI

get_sort_indexes([item_type, translate, locale])

Get a list of available sort item indexes and names

get_translations([locale])

Get all translations for given locale

get_view_count([item_type, item_id, …])

Get count of items in view

library_view([item_type, item_id, …])

Fetch items from the database.

submit_temporary_view([view_type, view_id])

not ready yet…

temporary_view([view_type, view_id, limit, …])

not ready yet…

translate(t_id[, locale, default, …])

Get a translation by translation id.

update_metatags_for_view([item_type, …])

Update metatags for items in view

Events

gallery_read_event([item_id, …])

An event for when a gallery has been read

page_read_event([item_id])

An event for when a page has been read

Item

add_to_filter([gallery_id, item_id, item])

Add a gallery to a filter

add_to_grouping([gallery_id, item_id, item])

Add a gallery to a grouping

gallery_exists([url, name])

Check if a gallery exists in the database

get_last_read_page([item_id])

Get the last page that was read for given gallery.

get_page([page_id, gallery_id, number, prev])

Get next/prev page by either gallery or page id

get_similar([item_type, item_id, limit])

Get similar items

load_gallery_from_path([path])

Load gallery data from a path

open_gallery([item_id, item_type, viewer_args])

Open a gallery or page in an external viewer

remove_from_collection([gallery_id, item_id])

Remove a gallery from a collection

remove_from_filter([gallery_id, item_id])

Remove a gallery from a filter

remove_from_grouping([gallery_id, item_id])

Remove a gallery from a grouping

scan_galleries(path[, scan_options, limit, …])

Scan for galleries in the given directory/archive

source_exists([item_type, item_id, check_all])

Check if gallery/page source exists on disk

sync_with_source([item_id, delete_existing, …])

Synchronise the gallery source with the database, meaning if the source is a path on the filesystem, it will rescan the source for any possibly new items for given item.

update_filters([item_ids])

Update filters

Gallery

add_to_filter([gallery_id, item_id, item])

Add a gallery to a filter

add_to_grouping([gallery_id, item_id, item])

Add a gallery to a grouping

gallery_exists([url, name])

Check if a gallery exists in the database

get_last_read_page([item_id])

Get the last page that was read for given gallery.

get_page([page_id, gallery_id, number, prev])

Get next/prev page by either gallery or page id

get_similar([item_type, item_id, limit])

Get similar items

load_gallery_from_path([path])

Load gallery data from a path

open_gallery([item_id, item_type, viewer_args])

Open a gallery or page in an external viewer

remove_from_collection([gallery_id, item_id])

Remove a gallery from a collection

remove_from_filter([gallery_id, item_id])

Remove a gallery from a filter

remove_from_grouping([gallery_id, item_id])

Remove a gallery from a grouping

scan_galleries(path[, scan_options, limit, …])

Scan for galleries in the given directory/archive

source_exists([item_type, item_id, check_all])

Check if gallery/page source exists on disk

sync_with_source([item_id, delete_existing, …])

Synchronise the gallery source with the database, meaning if the source is a path on the filesystem, it will rescan the source for any possibly new items for given item.

update_filters([item_ids])

Update filters

General

Error

Unable to execute python code at api.rst:330:

No module named ‘happypanda.interface.general’

Tags

get_common_tags([item_type, item_id, limit])

Get the most common tags for item

get_tags([item_type, item_id, raw])

Get tags for item

get_tags_count()

Get count of namespacetags in the database

search_tags([search_query, search_options, …])

Search for tags

update_item_tags([item_type, item_id, tags])

Update tags on an item

Database

delete_items([item_type, item_ids, options])

Remove an item from the database PERMANENTLY

get_count([item_type])

Get count of items in the database

get_image([item_type, item_ids, size, url, uri])

Get image for item.

get_item([item_type, item_id])

Get item

get_items([item_type, limit, offset])

Get a list of items

get_related_count([item_type, item_id, …])

Get count of items related to given item

get_related_items([item_type, item_id, …])

Get item related to given item and count

new_item([item_type, item, options])

Create a new item and add it to the database

search_items([item_type, search_query, …])

Search for items

update_item([item_type, item, options])

Update an existing item

update_metatags([item_type, item_id, …])

Update metatags for an item

Plugin

disable_plugin([plugin_id])

Disable a plugin

get_plugin([plugin_id])

Get information for a specific plugin

get_plugin_config([plugin_id])

Get configuration for a specific plugin

install_plugin([plugin_id])

Install a plugin

list_plugins([state])

Get a list plugins

remove_plugin([plugin_id])

Remove a plugin

send_plugin_message([plugin_id, msg])

Send a message to a plugin for a specific plugin

set_plugin_config([plugin_id, cfg])

Set/update configuration for a specific plugin

update_plugin([plugin_ids, force, push])

Check for new release and update the application

Configuration

get_item_config([item_type, item_id, cfg, yaml])

Get item configuration.

save_config()

Save config to disk

set_config(cfg)

Set/update configuration

set_item_config([item_type, item_id, cfg, yaml])

Set/update item configuration

Functions

Meta

add_item_to_queue(item_id=0, item_type=<ItemType.Gallery: 1>, options={}, queue_type=<QueueType.Metadata: 1>, priority=<Priority.Medium: 2>)

Add an item to a queue

Parameters
  • item_id (int) – id of item

  • item_type (ItemType) – type of item to get, note that each queue type has its own list of item types it supports

  • options (dict) – queue options

  • queue_type (QueueType) – type of queue

  • priority (Priority) – priority of item in queue

Returns

bool indicating whether the addition was successful

add_items_to_metadata_queue(items_kind=<ItemsKind.tags_missing_items: 4>, item_type=<ItemType.Gallery: 1>, options={}, priority=<Priority.Medium: 2>)

Add items to the metadata queue

Parameters
  • items_kind (ItemsKind) – kind of items to add

  • item_type (ItemType) – type of items to add

  • options (dict) – queue options

  • priority (Priority) – priority of item in queue

Returns

bool indicating whether the addition was succesful

add_urls_to_download_queue(urls=[], identifier=[], options={}, priority=<Priority.Medium: 2>)

Add a list of urls to the download queue

Parameters
  • urls (list) – list of urls

  • identifier – list of specific download handlers to match against

  • options (dict) – download options

  • priority (Priority) – priority of items in queue

Returns

bool indicating whether the addition was successful

check_update(push=False)

Check for new release

Parameters

push (bool) – whether to push out notifications if an update is found

Returns

{
    'url' : str,
    'tag' : str
    'changes' : str,
}

or null

Async function – This function returns a command id. Retrieve the value of the function with get_command_value(). See Asynchronous Commands for more information.

See also

get_changelog() – when a new update is found, its changelog is immediately available here update_application()

clear_queue(queue_type=<QueueType.Metadata: 1>)

Clear a queue

Parameters

queue_type (QueueType) – type of queue

Returns

bool indicating whether the action was successful

get_changelog()

Get the changelog in markdown formatted text The changelog returned is for the current release or a new update

Returns

{
    'version': str,
    'changes': str
}

See also

check_update()

get_command_progress(command_ids=None)

Get progress of command operation

If the command did not set a maximum value, the returned percent will be set to less than 0.0 for infinity.

This should be polled every few seconds to get updated values.

Parameters

command_ids (Optional[list]) – list of command ids or None to retrieve progress of all occurring commands

Returns

{
    command_id : {  'title': str,
                    'value': float,
                    'subtitle': str,
                    'subtype': :py:class:`.ProgressType`,
                    'max': float,
                    'percent': float,
                    'type': :py:class:`.ProgressType`,
                    'text': str,
                    'timestamp':int,
                    'state': :py:class:`.CommandState`
                    }
}

or

{
    command_id : None
}

or, if command_ids is None:

[
    {   'title': str,
        'value': float,
        'subtitle': str,
        'subtype': :py:class:`.ProgressType`,
        'max': float,
        'percent': float,
        'type': :py:class:`.ProgressType`,
        'text': str,
        'timestamp':int
        },
    ...
]

get_command_state(command_ids)

Get state of command

Parameters

command_ids (list) – list of command ids

Returns

{
    command_id : :py:class:`.CommandState`
}

get_command_value(command_ids, raise_error=True)

Get the returned command value

Parameters
  • command_ids (list) – list of command ids

  • raise_error – raise error if command failed or has not finished running

Returns

{
    command_id : value
}

get_download_info()

Get a list of download handlers

Args:

Returns

a list of download handlers sorted by priority

get_locales()

Retrieve available translation locales

Returns

{
    str : {
                'locale' : str
                'namespaces': [str, ...]
            }
}

See also

translate()

get_log(log_type=None)

Get log

Parameters

log_type (Optional[LogType]) – type of log to fetch

Returns

{

‘log’: a formatted str of the logs

}

get_login_info(identifier=None)

Get a list of logins

Parameters

identifier (Optional[str]) – name of the login identifier, this was set by the plugin

Returns

{

‘identifier’: text ‘name’: text ‘status’: status set by plugin ‘logged_in’: bool ‘user’: current logged in user ‘sites’: list of supported sites set by plugin ‘description’: description set by plugin

}

Return type

a list of logins or if an identifier was provided

get_metadata_info()

Get a list of metadata handlers

Args:

Returns

a list of metadata handlers sorted by priority

get_notifications()

Pull unread notifications

Returns

a list of notification message objects

Remarks:

The first call to this function is used to lazily connect the client to the notification system, and as such will always return an empty list

get_properties()

Get various server properties

Returns

a Properties message object

get_queue_items(limit=100, queue_type=<QueueType.Metadata: 1>)

Get current items in a queue

Parameters
  • limit (int) – limit the amount of items returned

  • queue_type (QueueType) – type of queue

Returns

[
]

get_queue_state(queue_type=<QueueType.Metadata: 1>, include_finished=True)

Get current state of a queue

Parameters
  • queue_type (QueueType) – type of queue

  • inculde_finished – include finished tasks

Returns

{
}

get_version()

Get version of components: ‘core’, ‘db’ and ‘torrent’

Returns

{
    'core' : [int, int, int],
    'db' : [int, int, int],
    'torrent' : [int, int, int],
}

mark_notification_read(ids)

Mark and unread notification as read

Parameters

ids (list) – a list of notification ids

Returns

status

reindex(limit=None)

Reindex datebase items

Parameters

limit (Optional[int]) – reindex only last x amount of items

Returns

{
    'status': bool,
}

Async function – This function returns a command id. Retrieve the value of the function with get_command_value(). See Asynchronous Commands for more information.

remove_item_from_queue(item_id=0, item_type=<ItemType.Gallery: 1>, queue_type=<QueueType.Metadata: 1>)

Add an item to a queue

Parameters
  • item_id (int) – id of item

  • item_type (ItemType) – type of item to get, note that each queue type has its own list of item types it supports

  • queue_type (QueueType) – type of queue

Returns

bool indicating whether the removal was succesful

restart_application(delay=10)

Restart the application

Parameters

delay (int) – delay in seconds before restarting

Returns

{
    'status': A ``bool`` indicating whether a restart was scheduled
}

shutdown_application(delay=10)

Shutdown the application

Parameters

delay (int) – delay in seconds before shutting down

Returns

{
    'status': A ``bool`` indicating whether a shutdown was scheduled
}

start_command(command_ids)

Start running a command

Parameters

command_ids (list) – list of command ids

Returns

{
    command_id : state
}

start_queue(queue_type=<QueueType.Metadata: 1>)

Start a queue

Parameters

queue_type (QueueType) – type of queue

Returns

bool indicating whether the action was successful

stop_command(command_ids)

Stop command from running

Parameters

command_ids (list) – list of command ids

Returns

{
    command_id : state
}

stop_queue(queue_type=<QueueType.Metadata: 1>)

Stop a queue

Parameters

queue_type (QueueType) – type of queue

Returns

bool indicating whether the action was successful

submit_login(identifier, credentials, options={})

Submit login credentials

Parameters
  • identifier (str) – name of the login identifier, this was set by the plugin

  • credentials (dict) – login credentials

  • options (dict) – login options

Returns

{
    'status': text,
    'logged_in': bool
}

Async function – This function returns a command id. Retrieve the value of the function with get_command_value(). See Asynchronous Commands for more information.

sweep_trash(options=None, force=False)

Sweep trashed items

Parameters
  • options (Optional[dict]) – trash options

  • force (bool) – force removal of items even if not due

Returns

bool

Async function – This function returns a command id. Retrieve the value of the function with get_command_value(). See Asynchronous Commands for more information.

update_application(download_url=None, restart=True)

Update the application with a new release. If download_url is not provided, a check for a new release will occur

Parameters
  • download_url (Optional[str]) – a url to the release file, can be path to file on the system

  • restart (bool) – restart the application after installing the new update

Returns

{
    'status': A ``bool`` indicating whether the install was successful or not
}

Async function – This function returns a command id. Retrieve the value of the function with get_command_value(). See Asynchronous Commands for more information.

See also

check_update()

UI

get_image_from_path(path, size=<ImageSize.Medium: 3>, url=False, uri=False)

Get image from given path or url. Image content is base64 encoded.

Parameters
  • path (str) – a supported path (note that the path must exist on this system if path points to a file/directory)

  • size (ImageSize) – size of image

  • url (bool) – replace image content with http url to image file

  • uri (bool) – turn raw base64 string into an URI

Returns

{
    item_id : command_id
}

Async function – This function returns a command id. Retrieve the value of the function with get_command_value(). See Asynchronous Commands for more information.

See also

get_image()

get_sort_indexes(item_type=None, translate=True, locale=None)

Get a list of available sort item indexes and names

Parameters
  • item_type (Optional[ItemType]) – return applicable indexes for a specific item type

  • translate (bool) – translate the sort expression name

  • locale (Optional[str]) – locale to get translations from (will override default locale)

Returns

[
    {
        'index' : int,
        'name': str,
        'item_type': int value of :py:class:`.ItemType`
    },
    ...
]

get_translations(locale=None)

Get all translations for given locale

You can find more about translations here.

Parameters

locale (Optional[str]) – locale to get translations from (will override default locale)

Returns

{
    'namespace.translation_id' : string
}

See also

get_locales()

get_view_count(item_type=<ItemType.Gallery: 1>, item_id=None, related_type=None, search_query='', search_options={}, filter_id=None, view_filter=<ViewType.Library: 1>)

Get count of items in view

Parameters
  • item_type (ItemType) – possible items are ItemType.Gallery, ItemType.Collection, ItemType.Grouping

  • search_query (str) – filter item by search terms

  • search_options (dict) – options to apply when filtering, see Settings for available search options. A mapping of ‘namespace.name’ : bool

  • filter_id (Optional[int]) – current ItemType.Filter item id

  • view_filter (ViewType) – type of view, set None to not apply any filter

  • related_type (Optional[ItemType]) – child item

  • item_id (Optional[int]) – id of parent item

Returns

{
    'count' : int
}

library_view(item_type=<ItemType.Gallery: 1>, item_id=None, related_type=None, page=0, limit=100, sort_by=None, sort_desc=False, search_query='', search_options={}, filter_id=None, view_filter=<ViewType.Library: 1>, include_profile=False, profile_sizes=[<enum 'ImageSize'>], url=False, uri=False)

Fetch items from the database. Provides pagination.

Parameters
  • item_type (ItemType) – possible items are ItemType.Gallery, ItemType.Collection, ItemType.Grouping

  • page (int) – current page (zero-indexed)

  • sort_by (Optional[ItemSort]) – either a ItemSort or a sort index

  • sort_desc (bool) – order descending (default is ascending)

  • limit (int) – amount of items per page

  • search_query (str) – filter item by search terms

  • search_options (dict) – options to apply when filtering, see Settings for available search options. A mapping of ‘namespace.name’ : bool

  • filter_id (Optional[int]) – current ItemType.Filter item id

  • view_filter (ViewType) – type of view, set None to not apply any filter

  • related_type (Optional[ItemType]) – child item

  • item_id (Optional[int]) – id of parent item

  • include_profile (bool) – include profile image data in items, note that this will introduce a performance hit

  • profile_sizes (list) – a list of ImageSize, only relevant when include_profile=true

Returns

[
    item message object,
    ...
]

submit_temporary_view(view_type=<TemporaryViewType.GalleryAddition: 1>, view_id=None)

not ready yet…

Parameters
  • view_type (TemporaryViewType) – type of temporary view

  • view_id (Optional[int]) – id of a specific view

Returns

[]

Async function – This function returns a command id. Retrieve the value of the function with get_command_value(). See Asynchronous Commands for more information.

temporary_view(view_type=<TemporaryViewType.GalleryAddition: 1>, view_id=None, limit=100, offset=0)

not ready yet…

Parameters
  • view_type (TemporaryViewType) – type of temporary view

  • view_id (Optional[int]) – id of a specific view

  • limit (int) – amount of items per page

  • offset (int) – offset the results by n items

Returns

{
    'items': [
            ...
        ],
    'count': int # count of all items in view
}

translate(t_id, locale=None, default=None, placeholder={}, count=None)

Get a translation by translation id. Raises error if a default value was not provided and no translation was found.

You can find more about translations here.

Parameters
  • t_id (str) – translation id

  • locale (Optional[str]) – locale to get translations from (will override default locale)

  • default (Optional[str]) – default text when no translation was found

  • placeholder (str) –

    ?

  • count (Optional[int]) – pluralization

Returns

string

See also

get_locales()

update_metatags_for_view(item_type=<ItemType.Gallery: 1>, metatags={}, item_id=None, related_type=None, page=0, limit=100, search_query='', search_options={}, filter_id=None, view_filter=<ViewType.Library: 1>)

Update metatags for items in view

Parameters
  • item_type (ItemType) – possible items are ItemType.Gallery, ItemType.Collection, ItemType.Grouping

  • metatags (dict) – a dict of { metatag_name : bool }

  • page (int) – current page (zero-indexed)

  • limit (int) – amount of items per page, set to None to apply to all items in the view

  • search_query (str) – filter item by search terms

  • search_options (dict) – options to apply when filtering, see Settings for available search options. A mapping of ‘namespace.name’ : bool

  • filter_id (Optional[int]) – current ItemType.Filter item id

  • view_filter (ViewType) – type of view, set None to not apply any filter

  • related_type (Optional[ItemType]) – child item

  • item_id (Optional[int]) – id of parent item

Returns: boolean

Async function – This function returns a command id. Retrieve the value of the function with get_command_value(). See Asynchronous Commands for more information.

Events

gallery_open_event(item_id=0)

An event for when a gallery is opened

Parameters

item_id (int) – id of gallery item

Returns

bool indicating whether the event was successful

gallery_read_event(item_id=0, update_to_last_page=True)

An event for when a gallery has been read

Parameters
  • item_id (int) – id of gallery item

  • update_to_last_page – update progress to last page

Returns

bool indicating whether the event was successful

page_read_event(item_id=0)

An event for when a page has been read

Parameters

item_id (int) – id of page item

Returns

bool indicating whether the event was successful

Remarks:

note that there is no need to call gallery_read_event() after a complete read if using this event (unless you want to force a complete read)

Item

add_item_log(item_type=<ItemType.Gallery: 1>, item_id=0, msg='', level=<LogLevel.INFO: 4>)

Log a message for item

Parameters
  • item_type (ItemType) – type of item to create

  • item_id (int) – id of item

  • msg (str) – log message

  • level (LogLevel) – log level

Returns

Status

get_item_log(item_type=<ItemType.Gallery: 1>, item_id=0)

Get logs for item

Parameters
  • item_type (ItemType) – type of item to create

  • item_id (int) – id of item

Returns

{

‘log’: a formatted str of the logs

}

Tags

get_all_tags(limit=100, offset=None)

Get all tags from the db

Parameters
  • limit (int) – limit the amount of items returned

  • offset (Optional[int]) – offset the results by n items

Returns

{
    namespace : [ tag message object, ...],
    ...
}

get_common_tags(item_type=<ItemType.Collection: 2>, item_id=0, limit=10)

Get the most common tags for item

Parameters
Returns

{
    namespace : [ tag message object, ...],
    ...
}

get_tags(item_type=<ItemType.Gallery: 1>, item_id=0, raw=False)

Get tags for item

Parameters
Returns

{
    namespace : [ tag message object, ...],
    ...
}

get_tags_count()

Get count of namespacetags in the database

Returns

{
    'count' : int
}

search_tags(search_query='', search_options={}, only_namespace=False, only_tag=False, sort_by=None, sort_desc=False, limit=100, offset=None)

Search for tags

Parameters
  • search_query (str) – search string

  • search_options (dict) – options to apply when filtering, see Settings for available search options

  • only_namespace (bool) – only search for matching namespace <not implemented yet>

  • only_tag (bool) – only search for matching tag <not implemented yet>

  • sort_by (Optional[ItemSort]) – either a ItemSort or a sort index

  • sort_desc (bool) – order descending (default is ascending)

  • limit (int) – limit the amount of items returned

  • offset (Optional[int]) – offset the results by n items

Returns

{
    namespace : [ tag message object, ...],
    ...
}

update_item_tags(item_type=<ItemType.Gallery: 1>, item_id=0, tags={})

Update tags on an item

Parameters
Returns

bool whether tags were updated or not

Database

delete_item(item_type=<ItemType.Gallery: 1>, item_id=0, options={})

Remove an item from the database PERMANENTLY

Parameters
  • item_type (ItemType) – type of item to create

  • item_id (int) – id of item

  • options (dict) – options to apply when deleting, see Settings for available options

Returns

[]

Async function – This function returns a command id. Retrieve the value of the function with get_command_value(). See Asynchronous Commands for more information.

delete_items(item_type=<ItemType.Gallery: 1>, item_ids=[], options={})

Remove an item from the database PERMANENTLY

Parameters
  • item_type (ItemType) – type of item to create

  • item_ids (list) – list with id of items

  • options (dict) – options to apply when deleting, see Settings for available options

Returns

boolean or None

Async function – This function returns a command id. Retrieve the value of the function with get_command_value(). See Asynchronous Commands for more information.

See also

delete_item()

get_count(item_type=<ItemType.Gallery: 1>)

Get count of items in the database

Parameters

item_type (ItemType) – type of item

Returns

{
    'count' : int
}

get_image(item_type=<ItemType.Gallery: 1>, item_ids=[], size=<ImageSize.Medium: 3>, url=False, uri=False)

Get image for item. Image content is base64 encoded.

Parameters
Returns

{
    item_id : command_id
}

Async function – This function returns a command id. Retrieve the value of the function with get_command_value(). See Asynchronous Commands for more information.

get_item(item_type=<ItemType.Gallery: 1>, item_id=0)

Get item

Parameters
  • item_type (ItemType) – type of item to get

  • item_id (int) – id of item

Returns

item message object

get_items(item_type=<ItemType.Gallery: 1>, limit=100, offset=None)

Get a list of items

Parameters
  • item_type (ItemType) – type of item to get

  • limit (int) – limit the amount of items returned

  • offset (Optional[int]) – offset the results by n items

  • include_count – include count of items in results

Returns

{
    'items' : [
            item message object,
            ...
        ]
    'count': total number of items
}

Get count of items related to given item

Parameters
  • item_type (ItemType) – parent item

  • item_id (int) – id of parent item

  • related_type (ItemType) – child item

Returns

{
    'id' : int
    'count' : int
}

Get item related to given item and count

Parameters
  • item_type (ItemType) – parent item

  • item_id (int) – id of parent item

  • related_type (ItemType) – child item

  • limit (int) – limit the amount of items returned

  • offset (Optional[int]) – offset the results by n items

  • include_count – include count of items in results

Returns

[
    related item message object,
    ...
]

new_item(item_type=<ItemType.Gallery: 1>, item={}, options={})

Create a new item and add it to the database

Parameters
  • item_type (ItemType) – type of item to create

  • item (dict) – item message object

Returns

bool

Async function – This function returns a command id. Retrieve the value of the function with get_command_value(). See Asynchronous Commands for more information.

search_items(item_type=<ItemType.Gallery: 1>, search_query='', search_options={}, sort_by=None, sort_desc=False, full_search=True, limit=100, offset=None)

Search for items

Parameters
  • item_type (ItemType) – all of ItemType except ItemType.Page

  • search_query (str) – filter item by search terms

  • search_options (dict) – options to apply when filtering, see Settings for available search options

  • sort_by (Optional[ItemSort]) – either a ItemSort or a sort index

  • sort_desc (bool) – order descending (default is ascending)

  • limit (int) – amount of items

  • offset (Optional[int]) – offset the results by n items

Returns

[
    item message object,
    ...
]

update_item(item_type=<ItemType.Gallery: 1>, item={}, options={})

Update an existing item

Parameters
  • item_type (ItemType) – type of item to create

  • item (dict) – item messeage object

Returns

bool indicating whether item was updated

update_metatags(item_type=<ItemType.Gallery: 1>, item_id=0, item_ids=[], metatags={})

Update metatags for an item

Parameters
Returns

None or boolean

Remarks:

If item_ids is used, this function will return a command id

Async function – This function returns a command id. Retrieve the value of the function with get_command_value(). See Asynchronous Commands for more information.

Plugin

check_plugin_update(plugin_ids=None, force=True, push=False)

Check for new plugin release

Parameters
  • plugin_ids (Optional[list]) – a list of plugin ids or None for check on all enabled or failed plugins

  • force (bool) – bypass user config on allowing checking for updates

  • push (bool) – whether to push out notifications if an update is found

Returns

{
'plugin_id': '',
'url':'',
'version':(0, 0, 0)
}

Return type

A list of found updates

Async function – This function returns a command id. Retrieve the value of the function with get_command_value(). See Asynchronous Commands for more information.

See also

update_plugin()

disable_plugin(plugin_id='')

Disable a plugin

Parameters

plugin_id (str) – UUID4 of plugin

Returns

status

get_plugin(plugin_id='')

Get information for a specific plugin

Parameters

plugin_id (str) – UUID4 of plugin

Returns

{
}

get_plugin_config(plugin_id='')

Get configuration for a specific plugin

Parameters

plugin_id (str) – UUID4 of plugin

Returns

{
'plugin_id': id of plugin,
'config': {}
}

install_plugin(plugin_id='')

Install a plugin

Parameters

plugin_id (str) – UUID4 of plugin

Returns

status

list_plugins(state=None)

Get a list plugins

Parameters

state (Optional[PluginState]) – filter list by plugin state

Returns

{
}

remove_plugin(plugin_id='')

Remove a plugin

Parameters

plugin_id (str) – UUID4 of plugin

Returns

status

send_plugin_message(plugin_id='', msg={})

Send a message to a plugin for a specific plugin

Parameters
  • plugin_id (str) – UUID4 of plugin

  • msg (dict) – message to send to plugin

Returns

message from plugin

set_plugin_config(plugin_id='', cfg={})

Set/update configuration for a specific plugin

Parameters
  • plugin_id (str) – UUID4 of plugin

  • cfg (dict) – a dict containing namespace.key:value

Returns

Status

update_plugin(plugin_ids=None, force=False, push=True)

Check for new release and update the application

Parameters
  • plugin_ids (Optional[list]) – a list of plugin ids or None for update on all enabled or failed plugins

  • force (bool) – bypass user config on allowing checking for updates

  • push (bool) – whether to push out notifications after an update

Returns

a list of plugin ids of the plugins that have been successfully updated

Async function – This function returns a command id. Retrieve the value of the function with get_command_value(). See Asynchronous Commands for more information.

Configuration

Most configuration keys can be stored and retrieved by namespace.key

See Settings for all server defined configuration keys and their default values.

There exists the special namespace this to retrieve and store configuration only visible to the client in question. The server will resolve the namespace this to the session owner’s name (the client that created the session). These configuration keys will appear in the server’s config.yaml file under the session owner’s name upon save.

get_config(cfg={})

Get configuration. See Settings.

Parameters

cfg (dict) – a dict containing namespace.key:default value or an empty dict to retrieve all settings

Returns

{
    'namespace.key': value
}

get_item_config(item_type=<ItemType.Gallery: 1>, item_id=0, cfg={}, yaml=True)

Get item configuration. See Settings.

Parameters
  • item_type (ItemType) – type of item to create

  • item_id (int) – id of item

  • cfg (dict) – a dict containing namespace.key:default value or an empty dict to retrieve all settings

  • yaml (bool) – a boolean whether to return a YAML formatted string

Returns

{
    'namespace.key': value
}

Return type

a str if yaml is set to true, else

save_config()

Save config to disk

Returns

Status

Remarks:

This is not related to item configuration

set_config(cfg)

Set/update configuration

Parameters

cfg (dict) – a dict containing namespace.key:value

Returns

Status

set_item_config(item_type=<ItemType.Gallery: 1>, item_id=0, cfg=None, yaml=None)

Set/update item configuration

Parameters
  • item_type (ItemType) – type of item to create

  • item_id (int) – id of item

  • cfg (Optional[dict]) – a dict containing namespace.key:value, mutually exclusive with yaml

  • yaml (Optional[str]) – a YAML formatted str of a namespace.key:value mapping, mutually exclusive with cfg

Returns

Status