Snakemake Executor Plugins Interface

9.4.0 · active · verified Thu Apr 16

This package provides a stable, versioned interface for interactions between Snakemake and its executor plugins. It defines the abstract base classes and data structures that plugin developers must implement to integrate custom execution backends with Snakemake. The current version is 9.4.0, and its release cadence is closely tied to major Snakemake releases, ensuring compatibility and stability for plugin development.

Common errors

```
ModuleNotFoundError: No module named 'snakemake_interface_executor_plugins'
```
cause The `snakemake-interface-executor-plugins` package is not installed in your Python environment.

fix Run `pip install snakemake-interface-executor-plugins` to install the package.
```
TypeError: Can't instantiate abstract class ExecutorBase with abstract methods cleanup, exec_job, ...
```
cause You are trying to instantiate an abstract base class or a subclass that has not implemented all required abstract methods.

fix Ensure that your concrete executor plugin class (e.g., `MyCustomExecutor`) implements all abstract methods defined in `ExecutorBase` (or `ExecutorSettingsBase` if you're subclassing that).
```
AttributeError: 'MyCustomExecutor' object has no attribute 'workflow_args'
```
cause The `ExecutorWorkflowArgs` object or its attributes were not correctly initialized or assigned within your custom executor plugin's `__init__` or `run` methods.

fix Ensure your executor plugin's `__init__` method correctly receives and stores the `workflow_args` parameter, typically passed by Snakemake when initializing the plugin.

Warnings

breaking Breaking changes in the interface can occur between major Snakemake versions (e.g., Snakemake 8 to 9). Existing plugins might require updates to adapt to new abstract methods or altered data structures.
Fix: Consult the official Snakemake release notes and the `snakemake-interface-executor-plugins` changelog for specific migration instructions when upgrading Snakemake.
gotcha When subclassing `ExecutorBase`, `ExecutorSettingsBase`, or other abstract classes, you must implement all abstract methods defined in the base class. Failure to do so will result in a `TypeError`.
Fix: Ensure all abstract methods (marked with `@abstractmethod` in the base class) are implemented in your concrete plugin class. Use `mypy` or similar type checkers during development to catch these issues early.
gotcha This package provides *interfaces* for Snakemake plugins, not a standalone executor. It should only be used by developers creating Snakemake executor plugins, not for general Snakemake usage or direct execution.
Fix: Understand that this package is a dependency for *plugin development*, defining the contract between Snakemake and a plugin. It's not intended for end-user interaction with Snakemake.
gotcha The version of `snakemake-interface-executor-plugins` must be compatible with your installed `snakemake` version. Using an incompatible version might lead to runtime errors or unexpected behavior.
Fix: Always install the `snakemake-interface-executor-plugins` version recommended or bundled with your `snakemake` installation, or check the official Snakemake documentation for compatibility matrix.

Install

pip install snakemake-interface-executor-plugins Install latest version

Imports

ExecutorSettingsBase

from snakemake_interface_executor_plugins.settings import ExecutorSettingsBase

CommonExecutorSettings

from snakemake_interface_executor_plugins.settings import CommonExecutorSettings

ExecutorBase

wrong:

from snakemake_interface_executor_plugins.executors.base_executor import ExecutorBase

correct:

from snakemake_interface_executor_plugins.executors.base import ExecutorBase

The 'base' module is the canonical import path; 'base_executor' might be an internal or deprecated path.

RemoteExecutor

from snakemake_interface_executor_plugins.executors.base import RemoteExecutor

ExecutorWorkflowArgs

from snakemake_interface_executor_plugins.workflow import ExecutorWorkflowArgs

Quickstart

This quickstart demonstrates how to define custom executor settings by subclassing `ExecutorSettingsBase`. This is a common first step for developing a Snakemake executor plugin, allowing the plugin to expose configurable parameters.

from snakemake_interface_executor_plugins.settings import ExecutorSettingsBase
from typing import Optional

# Define custom settings for a hypothetical executor plugin
class MyCustomExecutorSettings(ExecutorSettingsBase):
    """
    Settings for MyCustomExecutor.
    """
    my_custom_param: str = "default_value"
    another_setting: Optional[int] = None

    def __post_init__(self):
        # Optional: Add validation or post-initialization logic
        if not self.my_custom_param:
            raise ValueError("my_custom_param cannot be empty")
        print(f"MyCustomExecutorSettings initialized: {self.my_custom_param}")

# Example of creating an instance of the custom settings
if __name__ == "__main__":
    try:
        settings = MyCustomExecutorSettings(my_custom_param="special_value")
        print(f"Custom param: {settings.my_custom_param}")
        
        invalid_settings = MyCustomExecutorSettings(my_custom_param="")
    except ValueError as e:
        print(f"Caught expected error for empty param: {e}")

view raw JSON →