Snakemake Interface Common

Warnings

• breaking Snakemake 8 introduced a breaking change by moving 'remote provider functionality' into dedicated 'storage plugins'. Developers maintaining custom remote providers need to migrate their implementations to the new storage plugin interface.
  Fix: Rewrite remote provider functionality as a Snakemake storage plugin, implementing the interfaces defined in `snakemake-interface-storage-plugins` (which in turn leverages `snakemake-interface-common`).
• breaking Snakemake 9 changed how custom loggers are provided, requiring the use of 'logger plugins'. Existing custom logger implementations need to be adapted to conform to the new logger plugin interface.
  Fix: Implement custom logging functionality as a Snakemake logger plugin, adhering to the interfaces provided by `snakemake-interface-logger-plugins`.
• gotcha When developing Snakemake plugins, only interact with methods and properties of Snakemake objects that are explicitly defined within the stable interface packages (e.g., `snakemake-interface-common`, `snakemake-interface-executor-plugins`). Accessing internal or undocumented parts of Snakemake objects is not guaranteed to be stable across releases and can lead to unexpected breakages.
  Fix: Strictly adhere to the public API and documented interfaces provided by `snakemake-interface-common` and other `snakemake-interface-*` packages for plugin development.
• gotcha Snakemake's profile handling (used for configuring plugins) has seen recent changes (e.g., in Snakemake 9.19.0), including defaulting to `profile.yaml` and allowing direct specification of YAML files. Plugin developers should be aware that user-provided configurations might vary based on these new profile mechanisms.
  Fix: Ensure plugin configuration logic is robust to different profile specification methods, and document how users can configure the plugin via the latest Snakemake profile features. Refer to Snakemake's CLI documentation for the most current profile usage.

Install

• pip install snakemake-interface-common PyPI

Imports

• CommonSettingsBase

  from snakemake_interface_common.settings import CommonSettingsBase

Quickstart

This quickstart demonstrates how a Snakemake plugin's common settings class would inherit from `CommonSettingsBase` provided by `snakemake-interface-common`. It shows how to define configuration parameters, including those that might be sensitive and loaded from environment variables, establishing a standardized interface for plugin configuration.

import os
from dataclasses import dataclass, field
from snakemake_interface_common.settings import CommonSettingsBase

@dataclass
class MyPluginCommonSettings(CommonSettingsBase):
    """
    A hypothetical plugin's common settings inheriting from CommonSettingsBase.
    This demonstrates how shared configuration parameters for a Snakemake plugin
    are defined using the interface.
    """
    my_plugin_param: str = field(
        default="default_plugin_value",
        metadata={
            "help": "A common setting for MyPlugin."
        }
    )
    # Example of a sensitive setting, typically loaded from an environment variable
    api_key: str = field(
        default=os.environ.get("MYPLUGIN_API_KEY", ""),
        metadata={
            "help": "API key for MyPlugin service (from MYPLUGIN_API_KEY env var).",
            "env_var": "MYPLUGIN_API_KEY",
            "sensitive": True,
        },
    )

# Instantiate the settings. In a real Snakemake plugin, these would be populated
# from command-line arguments or Snakemake profiles.
settings = MyPluginCommonSettings(my_plugin_param="custom_value_from_profile_or_cli")

print(f"My plugin parameter: {settings.my_plugin_param}")
if settings.api_key:
    print("API Key loaded (value not shown for security).")
else:
    print("MYPLUGIN_API_KEY environment variable not set.")

# This class is primarily for defining structure; direct executable quickstarts
# are more relevant for full Snakemake plugins.