MO2 Python Plugin API

https://www.modorganizer.org/python-plugins-doc
Admin
This documentation provides a guide and API reference for developers to write Python plugins that...
Tokens:107,897
Snippets:827
Trust Score:8.3
Update:8 months ago
Show doc for...
Tokens:
Raw
### Installation Start Notification

Source: https://www.modorganizer.org/python-plugins-doc/_sources/autoapi/mobase/index.rst

This method is called at the very beginning of an installation process, before any other installer logic. It receives information about the archive being installed and whether it's a reinstallation.

```APIDOC
## POST /installer/on_installation_start

### Description
Callback function executed at the beginning of an installation process.

### Method
POST

### Endpoint
/installer/on_installation_start

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **archive** (string) - Required - The path to the archive file being installed.
- **reinstallation** (boolean) - Required - True if this is a reinstallation of an existing mod.
- **current_mod** (object | null) - Information about the mod being reinstalled or a potentially matching mod, or null if none.
  - *Details of the current_mod object structure would be defined here.*

### Request Example
```json
{
  "archive": "/path/to/downloaded_mod.zip",
  "reinstallation": false,
  "current_mod": null
}
```

### Response
#### Success Response (200)
- **status** (string) - Indicates the success of the callback (e.g., "acknowledged").

#### Response Example
```json
{
  "status": "acknowledged"
}
```
```

--------------------------------

### Handle Installation Start in Mod Organizer Plugin

Source: https://www.modorganizer.org/python-plugins-doc/autoapi/mobase/index

This method is invoked at the very beginning of an installation process, before any other methods are called. It's called once per installation, even for recursive operations. It provides details about the archive being installed, whether it's a reinstallation, and the current mod context.

```python
def onInstallationStart(_archive : str_, _reinstallation : bool_, _current_mod : IModInterface_) -> None:
    """
    Method calls at the start of the installation process, before any other methods. This method is only called once per installation process, even for recursive installations (e.g. with the bundle installer).
    If reinstallation is true, then the given mod is the mod being reinstalled (the one selected by the user). If reinstallation is false and currentMod is not null, then it corresponds to a mod MO2 thinks corresponds to the archive (e.g. based on matching Nexus ID or name).
    The default implementation does nothing.

    Parameters:
        archive – Path to the archive that is going to be installed.
        reinstallation – True if this is a reinstallation, False otherwise.
        current_mod – A currently installed mod corresponding to the archive being installed, or None if there is no such mod.
    """
    pass
```

--------------------------------

### Installer Plugins

Source: https://www.modorganizer.org/python-plugins-doc/plugin-types

Documentation for creating installer plugins, which are invoked when a user attempts to install a mod. Covers simple and complex installer types and their respective interfaces.

```APIDOC
## Installer Plugins

### Description
These plugins are invoked when the user tries to install a mod, either by double clicking in the download view or through the “Install Mod..” button or “Reinstall mod” item from the mod lists context menu. There are two ways to write an installer: simple or complex.

### Interfaces
`IPluginInstaller`, `IPluginInstallerSimple`, `IPluginInstallerCustom`

### Examples
`installer_bain`, `installer_bundle`, `installer_fomod`, `installer_ncc`, `installer_quick`, `installer_manual`

### Types of Installers
*   **Simple Installers**: MO handles the unpacking of the file (works with standard archive formats). The plugin selects files/folders for extraction and their destination.
*   **Complex Installers**: More flexible but require more implementation effort.
```

--------------------------------

### Register About-to-Run Callback (Python)

Source: https://www.modorganizer.org/python-plugins-doc/autoapi/mobase/index

Installs a callback function to be executed just before an application starts. Multiple handlers can be registered. If any handler returns False, the application launch is prevented.

```python
onAboutToRun(_callback : Callable[[str, PyQt6.QtCore.QDir, str], bool]_) → bool
onAboutToRun(_callback : Callable[[str], bool]_) → bool
```

--------------------------------

### Start Application

Source: https://www.modorganizer.org/python-plugins-doc/_sources/autoapi/mobase/index.rst

Starts an external application with specified arguments, working directory, and profile settings.

```APIDOC
## Start Application

### Description
Launches an external executable with optional arguments, custom working directory, and profile context. It can also handle custom overwrite paths.

### Method
`startApplication(executable: Union[str, os.PathLike[str], PyQt6.QtCore.QFileInfo], args: Sequence[str] = [], cwd: Union[str, os.PathLike[str], PyQt6.QtCore.QDir] = '', profile: str = '', forcedCustomOverwrite: str = '', ignoreCustomOverwrite: bool = False) -> int`

### Endpoint
(N/A - This is a method call within the plugin environment)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **executable** (Union[str, os.PathLike[str], PyQt6.QtCore.QFileInfo]) - Required - The path to the executable to run.
- **args** (Sequence[str]) - Optional - A list of command-line arguments to pass to the executable. Defaults to an empty list.
- **cwd** (Union[str, os.PathLike[str], PyQt6.QtCore.QDir]) - Optional - The working directory for the new process. Defaults to an empty string.
- **profile** (str) - Optional - The name of the profile to use for the new process. Defaults to an empty string.
- **forcedCustomOverwrite** (str) - Optional - A path to force as the custom overwrite directory. Defaults to an empty string.
- **ignoreCustomOverwrite** (bool) - Optional - If True, ignores any custom overwrite settings. Defaults to False.

### Request Example
```python
# Start an external tool with arguments
startApplication("/usr/bin/mytool", args=["--verbose", "--config", "myconfig.json"])

# Start with a specific working directory and profile
# startApplication("C:\Tools\MyApp.exe", cwd="C:\MyGame", profile="MyGameProfile")
```

### Response
#### Success Response (200)
- **return_code** (int) - The exit code of the started application. Returns 0 if the application was started successfully, or a non-zero value indicating an error.

#### Response Example
```json
{
  "return_code": 0
}
```
```

--------------------------------

### Basic MO2 Python Plugin Structure for Testing

Source: https://www.modorganizer.org/python-plugins-doc/setup-tools

A minimal Python class structure for testing Mod Organizer 2 plugin integration. This example demonstrates the basic `IPluginTool` interface and `init` method, useful for verifying VS Code's linting and auto-completion setup.

```python
import mobase


class MyPlugin(mobase.IPluginTool):
    def __init__(self):
        super().__init__()

    def init(self, organizer: mobase.IOrganizer) -> bool:
        organizer.dow  # (1)
        return True

    def name(self) -> int:
        return 0


def createPlugin() -> mobase.IPlugin:
    return MyPlugin()

```

--------------------------------

### IPluginInstallerSimple

Source: https://www.modorganizer.org/python-plugins-doc/autoapi/mobase/index

Interface for simple mod installers. Simple installers work with an in-memory file tree and can modify it before extraction.

```APIDOC
## Class _mobase.IPluginInstallerSimple

### Description
Simple installer for mods. Simple installers only deal with an in-memory structure representing the archive and can modify what to install and where by editing this structure. Actually extracting the archive is handled by the manager.

Bases: `IPluginInstaller`

### Methods

#### `_install(_name: GuessedString, _tree: IFileTree, _version: str, _nexus_id: int) -> InstallResult | IFileTree | tuple[InstallResult, IFileTree, str, int]`

Install a mod from an archive filetree.
The installer can modify the given tree and use the manager to extract or create new files.
This method returns different type of objects depending on the actual result of the installation. The C++ bindings for this method always returns a tuple (result, tree, version, id).

##### Parameters

* **_name** (GuessedString) - Name of the mod to install. As an input parameter this is the suggested name (e.g. from meta data) The installer may change this parameter to rename the mod).
* **_tree** (IFileTree) - In-memory representation of the archive content.
* **_version** (str) - Version of the mod, or an empty string is unknown.
* **_nexus_id** (int) - ID of the mod, or -1 if unknown.

##### Returns

* **InstallResult | IFileTree | tuple[InstallResult, IFileTree, str, int]** - In case of failure, the result of the installation, otherwise the modified tree or a tuple (result, tree, version, id) containing the result of the installation, the modified tree, the new version and the new ID. The tuple can be returned even if the installation did not succeed.
```

--------------------------------

### Plugin Type Examples (Python)

Source: https://www.modorganizer.org/python-plugins-doc/_sources/writing-plugins.rst

This Python code snippet shows examples of how to create different types of plugins by inheriting from specific classes provided by the `mobase` library. It demonstrates creating a Tool plugin (`IPluginTool`) and a Preview plugin (`IPluginPreview`).

```python
class MyTool(mobase.IPluginTool):  # Create a Tool plugin
    ...

class MyPreview(mobase.IPluginPreview):  # Create a preview plugin
    ...
```

--------------------------------

### Game Installation Path Configuration

Source: https://www.modorganizer.org/python-plugins-doc/_sources/autoapi/mobase/index.rst

This method is called during instance creation when the game's installation path is not automatically detected and requires user input. It's crucial for plugins that need to know the exact game installation directory.

```APIDOC
## POST /game/installation/path

### Description
Allows plugins to specify the game installation path when it cannot be auto-detected.

### Method
POST

### Endpoint
/game/installation/path

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **path** (string) - Required - The absolute path to the game installation directory.

### Request Example
```json
{
  "path": "/path/to/your/game/installation"
}
```

### Response
#### Success Response (200)
- **status** (string) - Indicates the success of the operation (e.g., "success").

#### Response Example
```json
{
  "status": "success"
}
```
```

--------------------------------

### Start Application with Virtual Filesystem

Source: https://www.modorganizer.org/python-plugins-doc/_sources/autoapi/mobase/index.rst

Starts an application with the virtual filesystem active. It allows specifying the executable, arguments, working directory, profile, and overwrite behavior. Returns a handle to the application or 0 on failure.

```python
def startApplication(executable: str, args: list[str] = None, cwd: str = None, profile: str = None, forcedCustomOverwrite: str = None, ignoreCustomOverwrite: bool = False) -> int:
    """
    Starts an application with virtual filesystem active.

    :param executable: Name or path of the executable. If this is only a filename, it will only work if it has been configured
                       in MO as an executable. If it is a relative path it is expected to be relative to the game directory.
    :param args: Arguments to pass to the executable. If the list is empty, and `executable` refers to a configured executable,
                 the configured arguments are used.
    :param cwd: The working directory for the executable. If this is empty, the path to the executable is used unless `executable`
                referred to a configured MO executable, in which case the configured cwd is used.
    :param profile: Profile to use. If this is empty (the default) the current profile is used.
    :param forcedCustomOverwrite: The mod to set as the custom overwrite, regardless of what the profile has configured.
    :param ignoreCustomOverwrite: Set to true to ignore the profile's configured custom overwrite.

    :returns: The handle to the started application, or 0 if the application failed to start.
    """
    pass
```

--------------------------------

### Application Launching

Source: https://www.modorganizer.org/python-plugins-doc/autoapi/mobase/index

Starts an application with the virtual filesystem active, allowing for custom configurations.

```APIDOC
## POST startApplication

### Description
Starts an application with virtual filesystem active.

### Method
POST

### Endpoint
/applications/start

### Parameters
#### Request Body
- **executable** (str | os.PathLike[str] | PyQt6.QtCore.QFileInfo_) - Required - Name or path of the executable.
- **args** (Sequence[str]) - Optional - Arguments to pass to the executable. Defaults to an empty list.
- **cwd** (str | os.PathLike[str] | PyQt6.QtCore.QDir) - Optional - The working directory for the executable. Defaults to an empty string.
- **profile** (str) - Optional - Profile to use. Defaults to the current profile.
- **forcedCustomOverwrite** (str) - Optional - The mod to set as the custom overwrite.
- **ignoreCustomOverwrite** (bool) - Optional - Set to true to ignore the profile’s configured custom overwrite. Defaults to False.

### Request Example
```json
{
  "executable": "my_game.exe",
  "args": ["-windowed"],
  "profile": "my_profile"
}
```

### Response
#### Success Response (200)
- **handle** (int) - The handle to the started application, or 0 if the application failed to start.

#### Response Example
```json
{
  "handle": 12345
}
```
```

--------------------------------

### IPluginInstallerCustom

Source: https://www.modorganizer.org/python-plugins-doc/autoapi/mobase/index

Interface for custom mod installers. Custom installers are responsible for handling archive extraction and installation logic.

```APIDOC
## Class _mobase.IPluginInstallerCustom

### Description
Custom installer for mods. Custom installers receive the archive name and have to go from there. They have to be able to extract the archive themselves.
Example of such installers are the external NCC installer or the OMOD installer.

Bases: `IPluginInstaller`

### Methods

#### `_install(_mod_name: GuessedString, _game_name: str, _archive_name: str, _version: str, _nexus_id: int) -> InstallResult`

Install the given archive.
The mod needs to be created by calling IOrganizer.createMod first.

##### Parameters

* **_mod_name** (GuessedString) - Name of the mod to install. As an input parameter this is the suggested name (e.g. from meta data) The installer may change this parameter to rename the mod).
* **_game_name** (str) - Name of the game for which the mod is installed.
* **_archive_name** (str) - Name of the archive to install.
* **_version** (str) - Version of the mod. May be empty if the version is not yet known. The plugin is responsible for setting the version on the created mod.
* **_nexus_id** (int) - ID of the mod or -1 if unknown. The plugin is responsible for setting the mod ID for the created mod.

##### Returns

* **InstallResult** - The result of the installation process.

#### `_isArchiveSupported(_tree: IFileTree) -> bool`

Check if the given file tree is a supported archive for this installer.

##### Parameters

* **_tree** (IFileTree) - The file tree to check.

##### Returns

* **bool** - True if this installer can handle the archive, False otherwise.

#### `_isArchiveSupported(_archive_name: str) -> bool`

Check if the given archive name is a supported archive for this installer.

##### Parameters

* **_archive_name** (str) - Name of the archive.

##### Returns

* **bool** - True if this installer can handle the archive, False otherwise.

#### `_supportedExtensions() -> set[str]`

Returns a set of file extensions that this installer can handle.

##### Returns

* **set[str]** - A list of file extensions that this installer can handle.
```

--------------------------------

### User Interface Initialization Handler

Source: https://www.modorganizer.org/python-plugins-doc/_sources/autoapi/mobase/index.rst

Install a handler to be called when the UI has been fully initialized.

```APIDOC
## POST /event/ui/initialized

### Description
Installs a handler to be called when the user interface has been fully initialized. The callback receives the main window object.

### Method
POST

### Endpoint
/event/ui/initialized

### Parameters
#### Query Parameters
- **callback** (Callable[[PyQt6.QtWidgets.QMainWindow], None]) - Required - The function to call when the UI has been fully initialized.

### Request Example
```json
{
  "callback": "my_ui_initialized_handler"
}
```

### Response
#### Success Response (200)
- **success** (bool) - True if the handler was installed properly.

#### Response Example
```json
{
  "success": true
}
```
```

--------------------------------

### Installation Manager Setting

Source: https://www.modorganizer.org/python-plugins-doc/_sources/autoapi/mobase/index.rst

Sets the installation manager for the installer plugin. This provides the installer with access to the core Mod Organizer installation functionalities.

```APIDOC
## POST /installer/set_installation_manager

### Description
Sets the installation manager for the installer plugin.

### Method
POST

### Endpoint
/installer/set_installation_manager

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **manager** (object) - Required - The installation manager interface.
  - *Details of the manager object structure would be defined here.*

### Request Example
```json
{
  "manager": { "type": "IInstallationManager" }
}
```

### Response
#### Success Response (200)
- **status** (string) - Indicates the success of the operation (e.g., "success").

#### Response Example
```json
{
  "status": "success"
}
```
```

--------------------------------

### Installation End Notification

Source: https://www.modorganizer.org/python-plugins-doc/_sources/autoapi/mobase/index.rst

This method is called after the installation process has concluded, providing details about the outcome and the newly installed mod.

```APIDOC
## POST /installer/on_installation_end

### Description
Callback function executed at the end of an installation process.

### Method
POST

### Endpoint
/installer/on_installation_end

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **result** (string) - Required - The outcome of the installation (e.g., "success", "failed").
- **new_mod** (object | null) - The newly installed mod interface if the installation was successful, otherwise null.
  - *Details of the new_mod object structure would be defined here.*

### Request Example
```json
{
  "result": "success",
  "new_mod": {
    "name": "Example Mod",
    "version": "1.0.0"
  }
}
```

### Response
#### Success Response (200)
- **status** (string) - Indicates the success of the callback (e.g., "acknowledged").

#### Response Example
```json
{
  "status": "acknowledged"
}
```
```

--------------------------------

### IInstallationManager API

Source: https://www.modorganizer.org/python-plugins-doc/autoapi/mobase/index

Provides methods for managing game installations, creating, extracting, and installing files and archives.

```APIDOC
## IInstallationManager API

### Description
Provides methods for managing game installations, including file operations and archive installations.

### Methods

#### createFile

##### Description
Creates a new file on the disk corresponding to the given entry. This method can be used by installers that need to create files that are not in the original archive. Temporary files are automatically cleaned up at the end of the installation.

##### Parameters
- **entry** (FileTreeEntry) - Required - The entry for which a temporary file should be created.

##### Returns
- **str** - The path to the created file, or an empty string if the file could not be created.

#### extractFile

##### Description
Extracts the specified file from the currently opened archive to a temporary location. This method cannot be used to extract directories. The call will fail with an exception if no archive is open. The temporary file is automatically cleaned up after the installation.

##### Parameters
- **entry** (FileTreeEntry) - Required - Entry corresponding to the file to extract.
- **silent** (bool) - Optional - If true, the dialog showing extraction progress will not be shown.

##### Returns
- **str** - The absolute path to the temporary file, or an empty string if the file was not extracted.

#### extractFiles

##### Description
Extracts the specified files from the currently opened archive to a temporary location. This method cannot be used to extract directories. The call will fail with an exception if no archive is open. The temporary files are automatically cleaned up after the installation.

##### Parameters
- **entries** (list[FileTreeEntry]) - Required - Entries corresponding to the files to extract.
- **silent** (bool) - Optional - If true, the dialog showing extraction progress will not be shown.

##### Returns
- **Sequence[str]** - A list containing absolute paths to the temporary files.

#### getSupportedExtensions

##### Description
Returns the extensions of archives supported by this installation manager.

##### Returns
- **Sequence[str]** - The extensions of archives supported by this installation manager.

#### installArchive

##### Description
Installs the given archive.

##### Parameters
- **mod_name** (GuessedString) - Required - Suggested name of the mod.
- **archive** (str | os.PathLike[str] | PyQt6.QtCore.QFileInfo_) - Required - Path to the archive to install.
- **mod_id** (int) - Optional - ID of the mod, if available.

##### Returns
- **tuple[InstallResult, str, int]** - The result of the installation.
```

--------------------------------

### Install Black and Flake8-Black for Code Formatting

Source: https://www.modorganizer.org/python-plugins-doc/_sources/setup-tools.rst

Installs the 'black' code formatter and 'flake8-black' plugin using pip. These tools ensure consistent code formatting across your project.

```bash
pip install black flake8-black
```

--------------------------------

### Handle Installation End in Mod Organizer Plugin

Source: https://www.modorganizer.org/python-plugins-doc/autoapi/mobase/index

This method is called once at the conclusion of an installation process, regardless of whether it was a simple or recursive installation. It receives the installation result and the newly created mod object if the installation was successful.

```python
def onInstallationEnd(_result : InstallResult_, _new_mod : IModInterface_) -> None:
    """
    Method calls at the end of the installation process. This method is only called once per installation process, even for recursive installations (e.g. with the bundle installer).

    Parameters:
        result – The result of the installation.
        new_mod – If the installation succeeded (result is RESULT_SUCCESS), contains the newly installed mod, otherwise it contains a null pointer.
    """
    pass
```

--------------------------------

### InstallResult Enum

Source: https://www.modorganizer.org/python-plugins-doc/autoapi/mobase/index

Enumeration for installation results.

```APIDOC
## Enum InstallResult

### Description
Represents the result of an installation operation.

### Members
- **CANCELED**: The operation was canceled.
- **FAILED**: The operation failed.
- **MANUAL_REQUESTED**: Manual intervention was requested.
- **NOT_ATTEMPTED**: The operation was not attempted.
- **SUCCESS**: The operation was successful.

### Example Usage
```python
from mobase import InstallResult

result = InstallResult.SUCCESS
if result == InstallResult.SUCCESS:
    print("Installation successful!")
```
```

--------------------------------

### Install Mod Archive (Python)

Source: https://www.modorganizer.org/python-plugins-doc/autoapi/mobase/index

Installs a mod from a given archive file. An optional name suggestion can be provided, though the user can still change it. Returns an interface to the installed mod or None if installation fails or is canceled.

```python
installMod(_filename : str | os.PathLike[str] | PyQt6.QtCore.QFileInfo_, _name_suggestion : str = ''_) → IModInterface
```

--------------------------------

### Manual Installer Check

Source: https://www.modorganizer.org/python-plugins-doc/_sources/autoapi/mobase/index.rst

Checks if the current installer plugin is a manual installer, which typically requires user interaction beyond automated extraction.

```APIDOC
## GET /installer/is_manual

### Description
Checks if this plugin acts as a manual installer.

### Method
GET

### Endpoint
/installer/is_manual

### Parameters
None

### Request Example
```json
{}
```

### Response
#### Success Response (200)
- **is_manual** (boolean) - True if this is a manual installer, False otherwise.

#### Response Example
```json
{
  "is_manual": false
}
```
```

--------------------------------

### Application Event Handlers

Source: https://www.modorganizer.org/python-plugins-doc/_sources/autoapi/mobase/index.rst

Install handlers to be called when an application has finished running.

```APIDOC
## POST /event/application/finished

### Description
Installs a handler to be called when an application has finished running. The callback receives the application path and its exit code.

### Method
POST

### Endpoint
/event/application/finished

### Parameters
#### Query Parameters
- **callback** (Callable[[str, int], None]) - Required - The function to call when an application has finished running.
- **immediate_if_possible** (bool) - Optional - If True, immediately run the callback if no refresh is currently running.

### Request Example
```json
{
  "callback": "my_finished_run_handler",
  "immediate_if_possible": true
}
```

### Response
#### Success Response (200)
- **success** (bool) - True if the handler was installed properly.

#### Response Example
```json
{
  "success": true
}
```
```

--------------------------------

### Install MO2 Stubs with Pip

Source: https://www.modorganizer.org/python-plugins-doc/_sources/setup-tools.rst

Installs the 'mobase-stubs' package, which provides type stubs for the MO2 Python module and PyQt5. This is essential for enabling auto-completion and type-checking in development environments.

```bash
pip install mobase-stubs
```

--------------------------------

### Install mobase Stubs for MO2 Python Plugins

Source: https://www.modorganizer.org/python-plugins-doc/setup-tools

Installs the necessary stubs for the 'mobase' module and PyQt5, which are essential for developing MO2 Python plugins. These stubs enable auto-completion and type-checking in development environments.

```shell
pip install mobase-stubs

```

--------------------------------

### Refresh Event Handlers

Source: https://www.modorganizer.org/python-plugins-doc/_sources/autoapi/mobase/index.rst

Install handlers to be called on the next refresh or immediately.

```APIDOC
## POST /event/refresh/next

### Description
Installs a handler to be called on the next refresh or immediately. The `immediate_if_possible` parameter controls whether the callback runs instantly if no refresh is in progress.

### Method
POST

### Endpoint
/event/refresh/next

### Parameters
#### Query Parameters
- **callback** (Callable[[], None]) - Required - Function to call on the next refresh (or immediately).
- **immediate_if_possible** (bool) - Optional - If True, immediately run the callback if no refresh is currently running.

### Request Example
```json
{
  "callback": "my_next_refresh_handler",
  "immediate_if_possible": true
}
```

### Response
#### Success Response (200)
- **success** (bool) - True if the handler was installed properly.

#### Response Example
```json
{
  "success": true
}
```
```

--------------------------------

### Python Enum Example: EndorsedState

Source: https://www.modorganizer.org/python-plugins-doc/autoapi/mobase/index

Demonstrates the usage of Python enumerations with the EndorsedState class. It shows how to define, access, and iterate through enum members, similar to the provided Color enum example.

```python
from enum import Enum

class Color(Enum):
    RED = 1
    BLUE = 2
    GREEN = 3

# Accessing members
print(Color.RED)

# Value lookup
print(Color(1))

# Name lookup
print(Color['RED'])

# Iteration
print(len(Color))
print(list(Color))
```

--------------------------------

### Get All Plugin Names

Source: https://www.modorganizer.org/python-plugins-doc/autoapi/mobase/index

Retrieves a sequence containing the names of all currently available plugins.

```python
def pluginNames() -> Sequence[str]:
    """
    Returns:
        The list of all plugin names.
    """
    pass
```

--------------------------------

### Plugin Setting Change Handler

Source: https://www.modorganizer.org/python-plugins-doc/_sources/autoapi/mobase/index.rst

Install a handler to be called when a plugin setting is changed.

```APIDOC
## POST /event/plugin/setting/changed

### Description
Installs a handler to be called when a plugin setting is changed. The callback receives the plugin name, setting name, old value, and new value.

### Method
POST

### Endpoint
/event/plugin/setting/changed

### Parameters
#### Query Parameters
- **callback** (Callable[[str, str, MoVariant, MoVariant], None]) - Required - The function to call when a plugin setting is changed.

### Request Example
```json
{
  "callback": "my_setting_changed_handler"
}
```

### Response
#### Success Response (200)
- **success** (bool) - True if the handler was installed properly.

#### Response Example
```json
{
  "success": true
}
```
```

--------------------------------

### Application Waiting

Source: https://www.modorganizer.org/python-plugins-doc/autoapi/mobase/index

Waits for a started application to finish and returns its exit status.

```APIDOC
## POST waitForApplication

### Description
Wait for the application corresponding to the given handle to finish. This will always show the lock overlay.

### Method
POST

### Endpoint
/applications/waitFor

### Parameters
#### Request Body
- **handle** (int) - Required - Handle of the application to wait for.
- **refresh** (bool) - Optional - Whether ModOrganizer should refresh after the process completed or not. Defaults to True.

### Request Example
```json
{
  "handle": 12345,
  "refresh": false
}
```

### Response
#### Success Response (200)
- **result** (bool) - True if the application completed successfully, False otherwise.
- **exitcode** (int) - The exit code of the application.

#### Response Example
```json
{
  "result": true,
  "exitcode": 0
}
```
```

--------------------------------

### Set Installation Manager in Mod Organizer Plugin

Source: https://www.modorganizer.org/python-plugins-doc/autoapi/mobase/index

Assigns the installation manager to the installer. Python plugins typically do not need to override this method, as they can access the installation manager directly via the _manager() method. This method is part of the installer's setup process.

```python
def setInstallationManager(_manager : IInstallationManager_) -> None:
    """
    Set the installation manager for this installer.
    Python plugins usually do not need to re-implement this and can directly access the installation manager using _manager().

    Parameters:
        manager – The installation manager.
    """
    pass
```

--------------------------------

### Get Plugin List Interface (Python)

Source: https://www.modorganizer.org/python-plugins-doc/autoapi/mobase/index

Retrieves an interface to the list of all available plugins. This interface can be used to query information about installed plugins.

```python
plugin_list = modorganizer.pluginList()
# Example: Iterate through plugins (assuming IPluginList has an iterable interface)
# for plugin in plugin_list:
#     print(plugin.name())
```

--------------------------------

### Get Mod List Interface (Python)

Source: https://www.modorganizer.org/python-plugins-doc/autoapi/mobase/index

Provides an interface to access and manage the list of installed mods. This is a central point for interacting with the mod collection.

```python
modList() → IModList
```

--------------------------------

### Get All Mod Names (Python)

Source: https://www.modorganizer.org/python-plugins-doc/autoapi/mobase/index

Retrieves a sequence of internal names for all installed mods. This is a fundamental function for identifying and referencing mods within the Mod Organizer environment.

```python
from mobase import IModList

# Assuming 'mod_list' is an instance of IModList
all_mods = mod_list.allMods()
print(all_mods)
```

--------------------------------

### Python Plugin Development Setup

Source: https://www.modorganizer.org/python-plugins-doc/index

This section outlines the steps to set up your development environment for MO2 Python plugins. It includes obtaining necessary stubs, configuring your IDE (Visual Studio Code), and optional configurations for code formatting and hot-reloading.

```python
# Example: Obtaining mobase stubs (conceptual)
# This would typically involve downloading or referencing a type stub file.
# from mobase.stubs import mobase

# Example: Configuring Visual Studio Code for mobase (conceptual)
# This would involve settings in .vscode/settings.json, e.g., for Pylance.
# {
#     "python.analysis.extraPaths": ["./stubs"]
# }

# Example: Configuring black for auto-formatting (conceptual)
# This would involve installing black and potentially configuring it in VS Code.
# pip install black

# Example: Automatically reloading plugins during development (conceptual)
# This might involve a custom script or a plugin that monitors file changes.
```

--------------------------------

### Get Mod Organizer Base Path

Source: https://www.modorganizer.org/python-plugins-doc/_sources/autoapi/mobase/index.rst

Returns the absolute path to the base directory of the Mod Organizer installation. This is essential for plugins that need to access or manage files within the Mod Organizer structure.

```python
def basePath() -> str:
    """
    :returns: The absolute path to the base directory of Mod Organizer.
    """
    pass
```

--------------------------------

### Previewer Plugins

Source: https://www.modorganizer.org/python-plugins-doc/plugin-types

Documentation for creating previewer plugins, which extend the data pane's ability to preview files. Currently supports image formats compatible with Qt.

```APIDOC
## Previewer Plugins

### Description
These plugins add support for previewing files in the data pane. Currently, all image formats supported by Qt are implemented, but not audio or 3D mesh formats.

### Interfaces
`IPluginPreview`

### Examples
`preview_base`
```

--------------------------------

### Installer Priority Retrieval

Source: https://www.modorganizer.org/python-plugins-doc/_sources/autoapi/mobase/index.rst

Retrieves the priority level of this installer plugin. Higher priority installers are preferred when multiple installers can handle the same archive.

```APIDOC
## GET /installer/priority

### Description
Retrieves the priority of this installer plugin.

### Method
GET

### Endpoint
/installer/priority

### Parameters
None

### Request Example
```json
{}
```

### Response
#### Success Response (200)
- **priority** (integer) - The priority value of the installer. Higher numbers indicate higher priority.

#### Response Example
```json
{
  "priority": 100
}
```
```

--------------------------------

### Python Enum Example (InstallResult)

Source: https://www.modorganizer.org/python-plugins-doc/_sources/autoapi/mobase/index.rst

Demonstrates the usage of Python's `enum.Enum` class, as exemplified by the `InstallResult` enumeration. It shows how to define an enumeration with name/value pairs and how to access members via attribute access, value lookup, or name lookup. It also illustrates iteration and length checking.

```python
class InstallResult(*args, **kwds):
    """
    Bases: :py:obj:`enum.Enum`

    Create a collection of name/value pairs.

    Example enumeration:

    >>> class Color(Enum):
    ...     RED = 1
    ...     BLUE = 2
    ...     GREEN = 3

    Access them by:

    - attribute access:

      >>> Color.RED
      <Color.RED: 1>

    - value lookup:

      >>> Color(1)
      <Color.RED: 1>

    - name lookup:

      >>> Color['RED']
      <Color.RED: 1>

    Enumerations can be iterated over, and know how many members they have:

    >>> len(Color)
    3

    >>> list(Color)
    [<Color.RED: 1>, <Color.BLUE: 2>, <Color.GREEN: 3>]

    Methods can be added to enumerations, and members can have their own
    attributes -- see the documentation for details.
    """
    pass
```

--------------------------------

### Implementing the IPlugin Interface

Source: https://www.modorganizer.org/python-plugins-doc/writing-plugins

Provides a template for implementing the core `IPlugin` interface methods. This includes initialization, defining plugin metadata (name, author, description, version), and handling activation status and settings.

```python
from typing import List

import mobase

class MyPlugin(mobase.IPlugin):

    _organizer: mobase.IOrganizer

    def __init__(self):
        super().__init__()  # You need to call this manually.

    def init(self, organizer: mobase.IOrganizer):
        self._organizer = organizer
        return True

    def name(self) -> str:
        return ""

    def author(self) -> str:
        return "Tannin"

    def description(self) -> str:
        return self._tr("Gives a friendly greeting")

    def version(self) -> mobase.VersionInfo:
        return mobase.VersionInfo(1, 0, 0, mobase.ReleaseType.FINAL)

    def isActive(self) -> bool:
        return self._organizer.pluginSetting(self.name(), "enabled")

    def settings(self) -> List[mobase.PluginSetting]:
        return [
            mobase.PluginSetting("enabled", "enable this plugin", True)
        ]
```

--------------------------------

### Check Manual Installer in Mod Organizer Installer Plugin

Source: https://www.modorganizer.org/python-plugins-doc/autoapi/mobase/index

Indicates whether the installer is a manual installer. Manual installers typically require user intervention or custom handling beyond direct archive extraction. This method returns a boolean value.

```python
def _isManualInstaller() -> bool:
    """
    Check if this installer is a manual installer.

    Returns:
        True if this installer is a manual installer, False otherwise.
    """
    pass
```

--------------------------------

### Register Mod Installed Callback (Python)

Source: https://www.modorganizer.org/python-plugins-doc/autoapi/mobase/index

Installs a callback function to be executed whenever a new mod is installed. The callback receives the newly installed mod's interface as an argument.

```python
from mobase import IModList, IModInterface

def on_mod_installed_handler(mod: IModInterface):
    print(f"Mod installed: {mod.name()}")

# Assuming 'mod_list' is an instance of IModList
success = mod_list.onModInstalled(on_mod_installed_handler)
print(f"Callback registration success: {success}")
```

--------------------------------

### Create a Basic Python Plugin for Mod Organizer

Source: https://www.modorganizer.org/python-plugins-doc/_sources/setup-tools.rst

This snippet demonstrates the basic structure of a Python plugin for Mod Organizer, including initialization and a placeholder for plugin logic. It requires the 'mobase' library.

```python
import mobase


class MyPlugin(mobase.IPluginTool):
    def __init__(self):
        super().__init__()

    def init(self, organizer: mobase.IOrganizer) -> bool:
        organizer.dow  # (1)
        return True

    def name(self) -> int:
        return 0


def createPlugin() -> mobase.IPlugin:
    return MyPlugin()
```

--------------------------------

### Create Multiple Plugin Instances (Python)

Source: https://www.modorganizer.org/python-plugins-doc/_sources/writing-plugins.rst

This Python code shows how to define multiple plugins using the `createPlugins` function. This function returns a list of `mobase.IPlugin` instances, allowing MO2 to load several plugins from a single file. Type hints are recommended for `mypy` compatibility.

```python
from typing import List

import mobase

class MyPlugin1(...):
    ...

class MyPlugin2(...):
    ...


def createPlugins() -> List[mobase.IPlugin]:
    return [MyPlugin1(), MyPlugin2()]
```

--------------------------------

### Retrieve Installer Priority in Mod Organizer Plugin

Source: https://www.modorganizer.org/python-plugins-doc/autoapi/mobase/index

Returns the priority of the installer. When multiple installers can handle an archive, the one with the highest priority value is selected. This allows for defining precedence among different installation methods.

```python
def _priority() -> int:
    """
    Retrieve the priority of this installer.
    If multiple installers are able to handle an archive, the one with the highest priority wins.

    Returns:
        The priority of this installer.
    """
    pass
```

--------------------------------

### mobase.widgets API Reference

Source: https://www.modorganizer.org/python-plugins-doc/autoapi/mobase/widgets/index

Documentation for the `mobase.widgets` subpackage, which provides custom Qt widgets for use in Mod Organizer 2 plugins.

```APIDOC
## API Reference: mobase.widgets

The `mobase.widgets` subpackage provides specialized Qt widgets for creating user interfaces within Mod Organizer 2 plugins.

### Classes

#### `TaskDialog`
- **Description**: A customizable dialog box for presenting choices or information to the user.
- **Usage**: Use this class to create interactive dialogs within your plugin.

#### `TaskDialogButton`
- **Description**: A specialized button designed for use within `TaskDialog` widgets.
- **Usage**: Instantiate this class to create buttons that can be added to a `TaskDialog`.
```

--------------------------------

### Plugin Initialization Function (createPlugins)

Source: https://www.modorganizer.org/python-plugins-doc/writing-plugins

Illustrates how to define the `createPlugins` function to instantiate multiple plugins from a single module. This function should return a list of `mobase.IPlugin` instances.

```python
# __init__.py (for multiple plugins)

import mobase
from .plugin1 import MyPlugin1
from .plugin2 import MyPlugin2

def createPlugins() -> list[mobase.IPlugin]:
    return [MyPlugin1(), MyPlugin2()]
```

--------------------------------

### Register UI Initialization Handler (Python)

Source: https://www.modorganizer.org/python-plugins-doc/autoapi/mobase/index

Installs a callback function that is called once the Mod Organizer user interface has been fully initialized. The callback receives the main application window (QMainWindow).

```python
from PyQt6.QtWidgets import QMainWindow

def on_ui_initialized_callback(main_window: QMainWindow):
    # Handle UI initialization logic here
    pass

modorganizer.onUserInterfaceInitialized(on_ui_initialized_callback)
```

--------------------------------

### Check Archive Support in Mod Organizer Installer Plugin

Source: https://www.modorganizer.org/python-plugins-doc/autoapi/mobase/index

Determines if the installer can handle a given archive. This method is called by the installation manager to check compatibility before proceeding with the installation process. It takes a file tree representation of the archive's content.

```python
def _isArchiveSupported(_tree : IFileTree_) -> bool:
    """
    Check if the given file tree corresponds to a supported archive for this installer.

    Parameters:
        tree – The tree representing the content of the archive.

    Returns:
        True if this installer can handle the archive, False otherwise.
    """
    pass
```

--------------------------------

### Plugin Initialization Callback

Source: https://www.modorganizer.org/python-plugins-doc/_sources/autoapi/mobase/index.rst

Provides a callback function to be executed once the user interface has been fully initialized. The callback receives the main application window as a parameter.

```APIDOC
## On Initialization Callback

### Description
Registers a callback function to be executed after the main application window is initialized. The callback receives the `QMainWindow` object.

### Method
(Implicitly called upon initialization, no explicit method to call for registration in this snippet)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```python
def my_callback(main_window):
    print("Main window initialized!")

# Assuming 'callback' is the parameter name for the registration function
# register_callback(callback=my_callback)
```

### Response
#### Success Response (200)
Returns `True` if the handler was installed properly. Currently, there are no known reasons for failure.

#### Response Example
```json
{
  "success": true
}
```
```

--------------------------------

### Custom Plugin Installer Interface

Source: https://www.modorganizer.org/python-plugins-doc/_sources/autoapi/mobase/index.rst

Defines the interface for custom plugin installers that handle archive extraction themselves. Custom installers receive the archive name and must implement methods to install mods, check archive support, and declare supported file extensions.

```python
class IPluginInstallerCustom:
    def install(self, mod_name: GuessedString, game_name: str, archive_name: str, version: str, nexus_id: int) -> InstallResult:
        """Install the given archive."""
        pass

    def isArchiveSupported(self, tree: IFileTree) -> bool:
        """Check if the given file is a supported archive for this installer."""
        pass
    
    def isArchiveSupported(self, archive_name: str) -> bool:
        """Check if the given file is a supported archive for this installer."""
        pass

    def supportedExtensions(self) -> set[str]:
        """Return a list of file extensions that this installer can handle."""
        pass
```

--------------------------------

### IPlugin Interface - Initialize

Source: https://www.modorganizer.org/python-plugins-doc/_sources/autoapi/mobase/index.rst

Abstract method to initialize the plugin. It receives the IOrganizer interface. This method may not be called if no IOrganizer is available.

```python
def init(organizer: IOrganizer) -> bool:
    """
    Initialize this plugin.

    Note that this function may never be called if no `IOrganizer` is available
    at that time, such as when creating the first instance in MO.

    Plugins will probably want to store the organizer pointer. It is guaranteed
    to be valid as long as the plugin is loaded.

    These functions may be called before `init()`:

      - `name()`
      - see `IPluginGame` for more.

    :param organizer: The main organizer interface.

    :returns: True if the plugin was initialized correctly, False otherwise.
    """
    pass
```

--------------------------------

### Simple Plugin Installer Interface

Source: https://www.modorganizer.org/python-plugins-doc/_sources/autoapi/mobase/index.rst

Defines the interface for simple plugin installers that operate on an in-memory file tree representation of an archive. These installers can modify the file tree and rely on the manager for actual extraction. The install method can return different types based on the outcome.

```python
class IPluginInstallerSimple:
    def install(self, name: GuessedString, tree: IFileTree, version: str, nexus_id: int) -> Union[InstallResult, IFileTree, tuple[InstallResult, IFileTree, str, int]]:
        """Install a mod from an archive filetree."""
        pass
```

--------------------------------

### Implement IPlugin Interface (Python)

Source: https://www.modorganizer.org/python-plugins-doc/_sources/writing-plugins.rst

This Python code provides a template for implementing the `IPlugin` interface within a Mod Organizer 2 plugin. It includes essential methods like `__init__`, `init`, `name`, `author`, `description`, `version`, `isActive`, and `settings`. The `init` method receives the `IOrganizer` object for plugin management.

```python
from typing import List

import mobase

class MyPlugin(...):  # The base class depends on the actual type of plugin

    _organizer: mobase.IOrganizer

    def __init__(self):
        super().__init__()  # You need to call this manually.

    def init(self, organizer: mobase.IOrganizer):
        self._organizer = organizer
        return True

    def name(self) -> str:
        return ""

    def author(self) -> str:
        return "Tannin"

    def description(self) -> str:
        return self._tr("Gives a friendly greeting")

    def version(self) -> mobase.VersionInfo:
        return mobase.VersionInfo(1, 0, 0, mobase.ReleaseType.FINAL)

    def isActive(self) -> bool:
        return self._organizer.pluginSetting(self.name(), "enabled")

    def settings(self) -> List[mobase.PluginSetting]:
        return [
            mobase.PluginSetting("enabled", "enable this plugin", True)
        ]
```

--------------------------------

### FileTreeEntry Path Methods

Source: https://www.modorganizer.org/python-plugins-doc/autoapi/mobase/index

Methods to retrieve the path of a FileTreeEntry. 'path' gets the path to the root, and 'pathFrom' gets the path from a specified parent tree.

```python
def path(_sep : str = '\\') → str:
    """
    Retrieve the path from this entry up to the root of the tree.
    This method propagate up the tree so is not constant complexity as the full path is never stored. 

    Parameters:
        
    **sep** – The type of separator to use to create the path. 

    Returns:
        
    The path from this entry to the root, including the name of this entry. 

def pathFrom(_tree : IFileTree_, _sep : str = '\\') → str:
    """
    Retrieve the path from the given tree to this entry. 

    Parameters:
        
      * **tree** – The tree to reach, must be a parent of this entry.
      * **sep** – The type of separator to use to create the path.



    Returns:
        
    The path from the given tree to this entry, including the name of this entry, or
    an empty string if the given tree is not a parent of this entry. 
    """
    ...
```
Tokens:
Raw