{"id":6883,"library":"snakemake-interface-common","title":"Snakemake Interface Common","description":"Snakemake-interface-common (current version 1.23.0) is a foundational Python package within the Snakemake ecosystem, providing common functions and abstract base classes for Snakemake and its various plugins. It defines stable interfaces that ensure compatibility and facilitate interaction between the main Snakemake workflow management system and extensions such as executor, storage, and logger plugins. The library adheres to semantic versioning to minimize breaking changes for plugin developers.","status":"active","version":"1.23.0","language":"en","source_language":"en","source_url":"https://github.com/snakemake/snakemake-interface-common","tags":["snakemake","workflow","interface","plugin","common","bioinformatics"],"install":[{"cmd":"pip install snakemake-interface-common","lang":"bash","label":"PyPI"}],"dependencies":[{"reason":"Requires Python 3.8 or newer.","package":"python","optional":false}],"imports":[{"symbol":"CommonSettingsBase","correct":"from snakemake_interface_common.settings import CommonSettingsBase"}],"quickstart":{"code":"import os\nfrom dataclasses import dataclass, field\nfrom snakemake_interface_common.settings import CommonSettingsBase\n\n@dataclass\nclass MyPluginCommonSettings(CommonSettingsBase):\n    \"\"\"\n    A hypothetical plugin's common settings inheriting from CommonSettingsBase.\n    This demonstrates how shared configuration parameters for a Snakemake plugin\n    are defined using the interface.\n    \"\"\"\n    my_plugin_param: str = field(\n        default=\"default_plugin_value\",\n        metadata={\n            \"help\": \"A common setting for MyPlugin.\"\n        }\n    )\n    # Example of a sensitive setting, typically loaded from an environment variable\n    api_key: str = field(\n        default=os.environ.get(\"MYPLUGIN_API_KEY\", \"\"),\n        metadata={\n            \"help\": \"API key for MyPlugin service (from MYPLUGIN_API_KEY env var).\",\n            \"env_var\": \"MYPLUGIN_API_KEY\",\n            \"sensitive\": True,\n        },\n    )\n\n# Instantiate the settings. In a real Snakemake plugin, these would be populated\n# from command-line arguments or Snakemake profiles.\nsettings = MyPluginCommonSettings(my_plugin_param=\"custom_value_from_profile_or_cli\")\n\nprint(f\"My plugin parameter: {settings.my_plugin_param}\")\nif settings.api_key:\n    print(\"API Key loaded (value not shown for security).\")\nelse:\n    print(\"MYPLUGIN_API_KEY environment variable not set.\")\n\n# This class is primarily for defining structure; direct executable quickstarts\n# are more relevant for full Snakemake plugins.","lang":"python","description":"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."},"warnings":[{"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`).","message":"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.","severity":"breaking","affected_versions":"Snakemake 8.x.x and earlier (for remote providers), affects plugins targeting these versions."},{"fix":"Implement custom logging functionality as a Snakemake logger plugin, adhering to the interfaces provided by `snakemake-interface-logger-plugins`.","message":"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.","severity":"breaking","affected_versions":"Snakemake 9.x.x and later, affects logger plugins."},{"fix":"Strictly adhere to the public API and documented interfaces provided by `snakemake-interface-common` and other `snakemake-interface-*` packages for plugin development.","message":"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.","severity":"gotcha","affected_versions":"All versions of `snakemake-interface-common` and related interface packages."},{"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.","message":"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.","severity":"gotcha","affected_versions":"Snakemake 9.19.0 and later."}],"env_vars":null,"last_verified":"2026-04-15T00:00:00.000Z","next_check":"2026-07-14T00:00:00.000Z","problems":[]}