BasePlugin

class forkbit_sdk.BasePlugin

Bases: object

Base class for all ForkBit plugins.

Subclass this and override on_ready() to build your plugin UI. The app creates an instance, injects context (project, settings, git), and calls on_ready() when everything is wired up.

Example:

from forkbit_sdk import BasePlugin
from PySide6.QtWidgets import QLabel, QVBoxLayout

class MyPlugin(BasePlugin):
    def on_ready(self):
        layout = QVBoxLayout(self.container)
        layout.addWidget(QLabel("Hello!"))

__init__()

container

The root widget for your plugin UI. Build your layout inside this.

git

Git operations for the current project. See GitClient.

property plugin_id: str

The unique plugin identifier (e.g. com.mycompany.myplugin).

property version: str

The plugin version from plugin.json.

property plugin_name: str

The display name shown in the sidebar.

property plugin_subtitle: str

The subtitle shown below the plugin name in the header.

property plugin_icon: str

The icon name (Lucide icon ID) for this plugin.

property plugin_icon_colors: tuple[str, str]

Gradient colors (start, end) for the plugin icon background.

property plugin_icon_path: str

Path to a custom icon file, if set.

property data_dir: Path

Per-instance directory for plugin file storage.

Created automatically by the app before on_ready() is called. Use read_json() and write_json() for convenient access.

Raises:

RuntimeError – If accessed before on_ready().

read_json(filename)

Read a JSON file from data_dir.

Parameters:

filename (str) – Name of the JSON file (e.g. "state.json").

Returns:

Parsed dict, or empty dict if the file doesn’t exist.

Return type:

dict

write_json(filename, data)

Atomic-write a JSON file to data_dir.

Writes to a temporary file first, then renames — safe against crashes.

Parameters:

• filename (str) – Name of the JSON file (e.g. "state.json").

• data (dict) – The dict to serialize.

Return type:

None

property settings: dict

Current plugin settings values as defined in settings.json.

secret_file(field_id)

Return the raw bytes for a secret_file settings field.

Parameters:

field_id (str) – The field ID from settings.json.

Returns:

Raw file content as bytes.

Raises:

KeyError – If no secret file is loaded for the given field.

Return type:

bytes

secret_file_stream(field_id)

Return a file-like BytesIO for a secret_file settings field.

Useful when a library expects a file object instead of raw bytes.

Parameters:

field_id (str) – The field ID from settings.json.

Returns:

A seekable BytesIO stream.

Return type:

BytesIO

property project_id: str

The unique ID of the currently open project.

property project_path: str

Filesystem path to the project directory.

on_ready()

Called when the plugin is fully initialized.

Override this to build your UI inside container and set up initial state. All context properties (settings, data_dir, git, etc.) are available at this point.

Return type:

None

on_settings_changed(settings)

Called when the user saves plugin settings.

Override this to react to settings changes at runtime (e.g. refresh data with a new API key). The base implementation updates settings — call super() if you override.

Parameters:

settings (dict) – The full updated settings dict.

Return type:

None

property status_chip: QWidget | None

Optional status chip widget in the plugin header.

Injected by the app — None until on_ready() runs.

set_subtitle(text)

Update the subtitle shown in the plugin header.

Parameters:

text (str) – New subtitle text (e.g. "v1.2.0 — 3 locales").

Return type:

None

notify(message, level='info')

Show a toast notification to the user.

Parameters:

• message (str) – The notification text.

• level (str) – One of "info", "success", "warning", "error".

Return type:

None

translate(text, source_lang, target_lang, on_done=None, on_error=None)

Request an asynchronous translation via the app’s translation service.

The translation runs in a background thread. Results arrive via callbacks.

Parameters:

• text (str) – The text to translate.

• source_lang (str) – Source language code (e.g. "en").

• target_lang (str) – Target language code (e.g. "de").

• on_done (Callable[[str], None] | None) – Callback receiving the translated text.

• on_error (Callable[[str], None] | None) – Callback receiving an error message.

Returns:

A request ID for tracking.

Raises:

RuntimeError – If no translation service is configured.

Return type:

str