External Application

Constants

class nc_py_api.ex_app.LogLvl(value)[source]

Log levels.

DEBUG = 0: Debug log level

INFO = 1: Informational log level

WARNING = 2: Warning log level. Default

ERROR = 3: Error log level

FATAL = 4: Fatal log level

Special functions

nc_py_api.ex_app.persistent_storage() → str[source]: Returns the path to directory, which is permanent storage and is not deleted when the application is updated.

nc_py_api.ex_app.verify_version(finalize_update: bool = True) → tuple[str, str] | None[source]

Returns tuple with an old version and new version or None if there was no update taken.

Parameters:: finalize_update – Flag indicating whether update information should be updated. If True, all subsequent calls to this function will return that there is no update.

User Interface(UI)

UI methods should be accessed with the help of NextcloudApp

# this is an example, in most cases you will get `NextcloudApp` class instance as input param.
nc = NextcloudApp()
nc.ex_app.ui.files_dropdown_menu.register(...)

class nc_py_api.ex_app.ui.ui.UiApi(session: NcSessionApp)[source]

Class that encapsulates all UI functionality.

files_dropdown_menu: _UiFilesActionsAPI: File dropdown menu API.

top_menu: _UiTopMenuAPI: Top App menu API.

resources: _UiResources: Page(Template) resources API.

settings: _DeclarativeSettingsAPI: API for ExApp settings UI

Nextcloud API for working with drop-down file’s menu.

class nc_py_api.ex_app.ui.files_actions.UiFileActionEntry(raw_data: dict)[source]

Files app, right click file action entry description.

property appid: str: App ID for which this entry is.

property name: str: File action name, acts like ID.

property display_name: str: Display name of the entry.

property mime: str: For which file types this entry applies.

property permissions: int: For which file permissions this entry applies.

property order: int: Order of the entry in the file action list.

property icon: str: Relative to the ExApp url with icon or empty value to use the default one icon.

property action_handler: str: Relative ExApp url which will be called if user click on the entry.

property version: str: AppAPI 2.6.0 supports new version of UiActions(https://github.com/cloud-py-api/app_api/pull/284).

class nc_py_api.ex_app.ui.files_actions._UiFilesActionsAPI(session: NcSessionApp)[source]

API for the drop-down menu in Nextcloud Files app, avalaible as nc.ui.files_dropdown_menu.<method>.

register(name: str, display_name: str, callback_url: str, **kwargs) → None[source]: Registers the files dropdown menu element.

register_ex(name: str, display_name: str, callback_url: str, **kwargs) → None[source]: Registers the files dropdown menu element(extended version that receives ActionFileInfoEx).

unregister(name: str, not_fail=True) → None[source]: Removes files dropdown menu element.

get_entry(name: str) → UiFileActionEntry | None[source]: Get information of the file action meny entry.

Nextcloud API for working with Top App menu.

class nc_py_api.ex_app.ui.top_menu.UiTopMenuEntry(raw_data: dict)[source]

App top menu entry description.

property appid: str: App ID for which this entry is.

property name: str: Top Menu entry name, acts like ID.

property display_name: str: Display name of the entry.

property icon: str: Relative to the ExApp url with icon or empty value to use the default one icon.

property admin_required: bool: Flag that determines whether the entry menu is displayed only for administrators.

class nc_py_api.ex_app.ui.top_menu._UiTopMenuAPI(session: NcSessionApp)[source]

API for the top menu app nav bar in Nextcloud, avalaible as nc.ui.top_menu.<method>.

register(name: str, display_name: str, icon: str = '', admin_required=False) → None[source]

Registers or edit the App entry in Top Meny.

Parameters:

name – Unique name for the menu entry.
display_name – Display name of the menu entry.
icon – Optional, url relative to the ExApp, like: “img/icon.svg”
admin_required – Boolean value indicating should be Entry visible to all or only to admins.

unregister(name: str, not_fail=True) → None[source]: Removes App entry in Top Menu.

get_entry(name: str) → UiTopMenuEntry | None[source]: Get information of the top meny entry for current app.

class nc_py_api.ex_app.ui.resources._UiResources(session: NcSessionApp)[source]

API for adding scripts, styles, initial-states to the pages, avalaible as nc.ui.resources.<method>.

set_initial_state(ui_type: str, name: str, key: str, value: dict | list) → None[source]: Add or update initial state for the page(template).

delete_initial_state(ui_type: str, name: str, key: str, not_fail=True) → None[source]: Removes initial state for the page(template) by object name.

get_initial_state(ui_type: str, name: str, key: str) → UiInitState | None[source]: Get information about initial state for the page(template) by object name.

set_script(ui_type: str, name: str, path: str, after_app_id: str = '') → None[source]: Add or update script for the page(template).

delete_script(ui_type: str, name: str, path: str, not_fail=True) → None[source]: Removes script for the page(template) by object name.

get_script(ui_type: str, name: str, path: str) → UiScript | None[source]: Get information about script for the page(template) by object name.

set_style(ui_type: str, name: str, path: str) → None[source]: Add or update style(css) for the page(template).

delete_style(ui_type: str, name: str, path: str, not_fail=True) → None[source]: Removes style(css) for the page(template) by object name.

get_style(ui_type: str, name: str, path: str) → UiStyle | None[source]: Get information about style(css) for the page(template) by object name.

class nc_py_api.ex_app.ui.resources.UiInitState(raw_data: dict)[source]

One Initial State description.

property key: str: Name of the object.

property value: dict | list: Object for the page(template).

class nc_py_api.ex_app.ui.resources.UiScript(raw_data: dict)[source]

One Script description.

property path: str: Url to script relative to the ExApp.

property after_app_id: str: Optional AppID after which script should be injected.

class nc_py_api.ex_app.ui.resources.UiStyle(raw_data: dict)[source]

One Style description.

property path: str: Url to style relative to the ExApp.

Section field.

classmethod from_dict(data: dict) → SettingsField[source]: Creates instance of class from dict, ignoring unknown keys.

to_dict() → dict[source]: Returns data in format that is accepted by AppAPI.

class nc_py_api.ex_app.ui.settings.SettingsForm(id: str, section_id: str, title: str, fields: list[~nc_py_api.ex_app.ui.settings.SettingsField] = <factory>, description: str = '', priority: int = 50, doc_url: str = '', section_type: str = 'personal')[source]

Settings Form and Section.

classmethod from_dict(data: dict) → SettingsForm[source]: Creates instance of class from dict, ignoring unknown keys.

to_dict() → dict[source]: Returns data in format that is accepted by AppAPI.

class nc_py_api.ex_app.ui.settings.SettingsFieldType(value)[source]

Declarative Settings Field Type.

TEXT = 'text': NcInputField type text

PASSWORD = 'password': NcInputField type password

EMAIL = 'email': NcInputField type email

TEL = 'tel': NcInputField type tel

URL = 'url': NcInputField type url

NUMBER = 'number': NcInputField type number

CHECKBOX = 'checkbox': NcCheckboxRadioSwitch type checkbox

MULTI_CHECKBOX = 'multi-checkbox': Multiple NcCheckboxRadioSwitch type checkbox representing a one config value (saved as JSON object)

RADIO = 'radio': NcCheckboxRadioSwitch type radio

SELECT = 'select': NcSelect

MULTI_SELECT = 'multi-select': Multiple NcSelect representing a one config value (saved as JSON array)

class nc_py_api.ex_app.ui.settings._DeclarativeSettingsAPI(session: NcSessionApp)[source]

Class providing API for creating UI for the ExApp settings, avalaible as nc.ui.settings.<method>.

register_form(form_schema: SettingsForm | dict[str, Any]) → None[source]: Registers or edit the Settings UI Form.

unregister_form(form_id: str, not_fail=True) → None[source]: Removes Settings UI Form.

get_entry(form_id: str) → SettingsForm | None[source]: Get information of the Settings UI Form.

class nc_py_api.ex_app.providers.providers.ProvidersApi(session: NcSessionApp)[source]

Class that encapsulates all AI Providers functionality.

task_processing: _TaskProcessingProviderAPI: TaskProcessing Provider API.

class nc_py_api.ex_app.providers.task_processing.ShapeType(value)[source]: Enum for shape types.

class nc_py_api.ex_app.providers.task_processing.ShapeEnumValue(name: str, value: str)[source]

Data object for input output shape enum slot value.

name: str: Name of the enum slot value which will be displayed in the UI

value: str: Value of the enum slot value

class nc_py_api.ex_app.providers.task_processing.ShapeDescriptor(name: str, description: str, shape_type: ShapeType)[source]

Data object for input output shape entries.

name: str: Name of the shape entry

description: str: Description of the shape entry

shape_type: ShapeType: Type of the shape entry

class nc_py_api.ex_app.providers.task_processing.TaskType(id: str, name: str, description: str, input_shape: list[ShapeDescriptor], output_shape: list[ShapeDescriptor])[source]

TaskType description for the provider.

id: str: The unique ID for the task type.

name: str: The localized name of the task type.

description: str: The localized description of the task type.

input_shape: list[ShapeDescriptor]: The input shape of the task.

output_shape: list[ShapeDescriptor]: The output shape of the task.

class nc_py_api.ex_app.providers.task_processing.TaskProcessingProvider(id: str, name: str, task_type: str, expected_runtime: int = 0, optional_input_shape: list[~nc_py_api.ex_app.providers.task_processing.ShapeDescriptor] = <factory>, optional_output_shape: list[~nc_py_api.ex_app.providers.task_processing.ShapeDescriptor] = <factory>, input_shape_enum_values: dict[str, list[~nc_py_api.ex_app.providers.task_processing.ShapeEnumValue]] = <factory>, input_shape_defaults: dict[str, str | int | float] = <factory>, optional_input_shape_enum_values: dict[str, list[~nc_py_api.ex_app.providers.task_processing.ShapeEnumValue]] = <factory>, optional_input_shape_defaults: dict[str, str | int | float] = <factory>, output_shape_enum_values: dict[str, list[~nc_py_api.ex_app.providers.task_processing.ShapeEnumValue]] = <factory>, optional_output_shape_enum_values: dict[str, list[~nc_py_api.ex_app.providers.task_processing.ShapeEnumValue]] = <factory>)[source]

id: str: Unique ID for the provider.

name: str: The localized name of this provider

task_type: str: The TaskType provided by this provider.

expected_runtime: int = 0: Expected runtime of the task in seconds.

optional_input_shape: list[ShapeDescriptor]: Optional input shape of the task.

optional_output_shape: list[ShapeDescriptor]: Optional output shape of the task.

input_shape_enum_values: dict[str, list[ShapeEnumValue]]: The option dict for each input shape ENUM slot.

input_shape_defaults: dict[str, str | int | float]: The default values for input shape slots.

optional_input_shape_enum_values: dict[str, list[ShapeEnumValue]]: The option list for each optional input shape ENUM slot.

optional_input_shape_defaults: dict[str, str | int | float]: The default values for optional input shape slots.

output_shape_enum_values: dict[str, list[ShapeEnumValue]]: The option list for each output shape ENUM slot.

optional_output_shape_enum_values: dict[str, list[ShapeEnumValue]]: The option list for each optional output shape ENUM slot.

class nc_py_api.ex_app.providers.task_processing._TaskProcessingProviderAPI(session: NcSessionApp)[source]

API for TaskProcessing providers, available as nc.providers.task_processing.<method>.

register(provider: TaskProcessingProvider, custom_task_type: TaskType | None = None) → None[source]: Registers or edit the TaskProcessing provider.

unregister(name: str, not_fail=True) → None[source]: Removes TaskProcessing provider.

next_task(provider_ids: list[str], task_types: list[str]) → dict[str, Any][source]: Get the next task processing task from Nextcloud.

set_progress(task_id: int, progress: float) → dict[str, Any][source]: Report new progress value of the task to Nextcloud. Progress should be in range from 0.0 to 100.0.

upload_result_file(task_id: int, file: bytes | str | Any) → int[source]: Uploads file and returns fileID that should be used in the report_result function.

Note

file can be any file-like object.

report_result(task_id: int, output: dict[str, Any] | None = None, error_message: str | None = None) → dict[str, Any][source]: Report result of the task processing to Nextcloud.

class nc_py_api.ex_app.events_listener.EventsListener(raw_data: dict)[source]

EventsListener description.

property event_type: str: Main type of event, e.g. node_event.

property event_subtypes: str: Subtypes for which fire event, e.g. NodeCreatedEvent, NodeDeletedEvent.

property action_handler: str: Relative ExApp url which will be called by Nextcloud.

class nc_py_api.ex_app.events_listener.EventsListenerAPI(session: NcSessionApp)[source]

API for registering Events listeners, avalaible as nc.events_handler.<method>.

register(event_type: str, callback_url: str, event_subtypes: list[str] | None = None) → None[source]: Registers or edits the events listener.

unregister(event_type: str, not_fail=True) → None[source]: Removes the events listener.

get_entry(event_type: str) → EventsListener | None[source]: Get information about the event listener.

class nc_py_api.ex_app.occ_commands.OccCommand(raw_data: dict)[source]

OccCommand description.

property name: str: Unique ID for the command.

property description: str: Command description.

property hidden: bool: Flag determining ss command hidden or not.

property arguments: dict: Look at PHP Symfony framework for details.

property options: str: Look at PHP Symfony framework for details.

property usages: str: Look at PHP Symfony framework for details.

property action_handler: str: Relative ExApp url which will be called by Nextcloud.

class nc_py_api.ex_app.occ_commands.OccCommandsAPI(session: NcSessionApp)[source]

API for registering OCC commands, avalaible as nc.occ_command.<method>.

register(name: str, callback_url: str, arguments: list | None = None, options: list | None = None, usages: list | None = None, description: str = '', hidden: bool = False) → None[source]: Registers or edit the OCC command.

unregister(name: str, not_fail=True) → None[source]: Removes the OCC command.

get_entry(name: str) → OccCommand | None[source]: Get information of the OCC command.