{"id":8654,"library":"snakemake-interface-report-plugins","title":"Snakemake Report Plugins Interface","description":"This library provides the abstract base classes, decorators, and type hints required to develop custom report plugins for Snakemake workflows. It defines the standardized interface that Snakemake uses to discover and interact with report plugins. As an interface package, it aims for API stability for plugin developers and generally follows Snakemake's major release cadence. The current version is 2.0.1 and requires Python 3.11 or newer.","status":"active","version":"2.0.1","language":"en","source_language":"en","source_url":"https://github.com/snakemake/snakemake-interface-report-plugins","tags":["snakemake","plugin","interface","report","workflow","bioinformatics"],"install":[{"cmd":"pip install snakemake-interface-report-plugins","lang":"bash","label":"Install latest version"}],"dependencies":[],"imports":[{"note":"ReportPluginBase is part of the public API module 'api', not directly in the top-level package.","wrong":"from snakemake_interface_report_plugins import ReportPluginBase","symbol":"ReportPluginBase","correct":"from snakemake_interface_report_plugins.api import ReportPluginBase"},{"note":"The registration decorator is part of the public API module 'api', not directly in the top-level package.","wrong":"from snakemake_interface_report_plugins import register_report_plugin","symbol":"register_report_plugin","correct":"from snakemake_interface_report_plugins.api import register_report_plugin"}],"quickstart":{"code":"import os\nfrom pathlib import Path\nfrom snakemake_interface_report_plugins.api import ReportPluginBase, register_report_plugin\n\n@register_report_plugin\nclass MyCustomReportPlugin(ReportPluginBase):\n \"\"\"\n A minimal Snakemake report plugin demonstrating the required interface.\n \"\"\"\n def __init__(\n self,\n report_dir: Path, \n report_paths: dict[str, Path],\n log_file: Path,\n **kwargs,\n ):\n super().__init__(report_dir, report_paths, log_file, **kwargs)\n self.plugin_id = kwargs.get(\"name\", \"my-custom-report\")\n # Custom initialization logic here\n\n def get_report_name(self) -> str:\n \"\"\"Returns the unique name for this report plugin.\"\"\"\n return self.plugin_id\n\n def get_report_css(self) -> list[Path]:\n \"\"\"Returns a list of paths to CSS files for the report.\"\"\"\n # In a real plugin, these would typically be relative paths to files\n # within the plugin's package, resolved by pkg_resources or importlib.resources.\n return []\n\n def get_report_js(self) -> list[Path]:\n \"\"\"Returns a list of paths to JS files for the report.\"\"\"\n return []\n\n def get_report_html(self, jobid: str) -> str:\n \"\"\"\n Generates the HTML content for a specific job ID.\n This content will be embedded into the final Snakemake report.\n \"\"\"\n return f\"\"\"\n
\n

Report for job: {jobid} from {self.plugin_id}

\n

Report directory: {self.report_dir}

\n

Log file: {self.log_file}

\n

Timestamp: {os.path.getmtime(self.log_file) if self.log_file.exists() else 'N/A'}

\n
\n \"\"\"\n\n# To demonstrate, a plugin needs to be discovered by Snakemake. \n# This example code does not run a Snakemake workflow, but shows \n# the structure of a plugin Python file.\n# In a real scenario, Snakemake would import and instantiate this class.\nif __name__ == \"__main__\":\n # Simulate Snakemake's environment for instantiation\n temp_dir = Path(\"./temp_plugin_test\").resolve()\n temp_dir.mkdir(exist_ok=True)\n sample_log_file = temp_dir / \"sample_log.txt\"\n sample_log_file.write_text(\"Log content here.\")\n \n # Snakemake would instantiate your plugin like this:\n mock_report_paths = {\"summary\": temp_dir / \"summary.html\"}\n plugin_instance = MyCustomReportPlugin(\n report_dir=temp_dir,\n report_paths=mock_report_paths,\n log_file=sample_log_file,\n name=\"demo-plugin-instance\"\n )\n \n print(f\"Plugin registered: {plugin_instance.get_report_name()}\")\n print(f\"Example HTML output for 'job_A':\\n{plugin_instance.get_report_html('job_A')}\")\n\n # Cleanup\n sample_log_file.unlink()\n temp_dir.rmdir()\n","lang":"python","description":"This quickstart demonstrates how to define a basic Snakemake report plugin. Plugins must inherit from `ReportPluginBase` and be decorated with `@register_report_plugin`. They implement methods like `get_report_name` and `get_report_html` to provide content to the Snakemake report. This file would typically be placed in a directory discoverable by Snakemake as a plugin source."},"warnings":[{"fix":"Update your plugin code to inherit `ReportPluginBase` and decorate the class with `@register_report_plugin` as shown in the quickstart. Review the official Snakemake plugin documentation for full details.","message":"Version 2.0.0 introduced significant breaking changes for plugin developers. The plugin registration mechanism was refactored, requiring plugins to explicitly inherit from `ReportPluginBase` and use the `@register_report_plugin` decorator. Older plugins designed for `snakemake-interface-report-plugins` v1.x will not be compatible.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Ensure your Snakemake installation is compatible with the plugin interface version. This library's API ensures your plugin is correctly structured, but Snakemake itself handles the execution.","message":"This library defines the *interface* for plugins, not the core logic for running Snakemake reports. While you implement the plugin using this interface, the plugin itself must be discovered and invoked by a compatible Snakemake core version (typically Snakemake >=8.0.0 for v2 plugins).","severity":"gotcha","affected_versions":"All versions"},{"fix":"Ensure all abstract methods of `ReportPluginBase` are implemented in your custom plugin class. Refer to the quickstart for a complete minimal example.","message":"Report plugins must implement all abstract methods defined in `ReportPluginBase`, such as `get_report_name`, `get_report_css`, `get_report_js`, and `get_report_html`. Failure to do so will result in `TypeError` when the plugin class is instantiated.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Upgrade your Python environment to version 3.11, 3.12, or newer (but less than 4.0).","message":"This library specifically requires Python 3.11 or newer (and less than 4.0). Using an older Python version will lead to installation failures or runtime errors.","severity":"gotcha","affected_versions":">=2.0.0"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Ensure the package is installed: `pip install snakemake-interface-report-plugins`. Verify the import path is `from snakemake_interface_report_plugins.api import ...`.","cause":"The `snakemake-interface-report-plugins` package is either not installed, or there's a typo in the import path.","error":"ModuleNotFoundError: No module named 'snakemake_interface_report_plugins.api'"},{"fix":"Implement all methods declared as abstract in `ReportPluginBase` in your plugin class. Refer to the quickstart example for required methods.","cause":"Your plugin class inherits from `ReportPluginBase` but has not implemented all of its abstract methods (e.g., `get_report_name`, `get_report_css`, `get_report_js`, `get_report_html`).","error":"TypeError: Can't instantiate abstract class MyPlugin with abstract methods get_report_name"},{"fix":"Ensure your plugin class explicitly inherits `ReportPluginBase`: `class MyPlugin(ReportPluginBase):`.","cause":"Your plugin class is decorated with `@register_report_plugin` but does not actually inherit from `snakemake_interface_report_plugins.api.ReportPluginBase`.","error":"snakemake.exceptions.PluginError: Plugin 'my-plugin' could not be registered: Class must inherit from ReportPluginBase"},{"fix":"Change your import statement to `from snakemake_interface_report_plugins.api import ReportPluginBase`.","cause":"You are trying to import `ReportPluginBase` directly from the top-level package instead of its specific `api` submodule.","error":"ImportError: cannot import name 'ReportPluginBase' from 'snakemake_interface_report_plugins'"}]}