snakemake-software-deployment-plugin-container 0.1.0__py3-none-any.whl

snakemake_software_deployment_plugin_container/__init__.py

@@ -0,0 +1,146 @@
+__author__ = "ben carrillo"
+__copyright__ = "Copyright 2025, ben carrillo"
+__email__ = "ben.uzh@pm.me"
+__license__ = "MIT"
+import os.path
+import shlex
+
+from dataclasses import dataclass, field
+from os import getcwd
+from shutil import which
+from typing import Iterable
+
+from snakemake_interface_software_deployment_plugins.settings import (
+    SoftwareDeploymentSettingsBase,
+)
+from snakemake_interface_software_deployment_plugins import (
+    EnvBase,
+    EnvSpecBase,
+    SoftwareReport,
+)
+
+# Raise errors that will not be handled within this plugin but thrown upwards to
+# Snakemake and the user as WorkflowError.
+from snakemake_interface_common.exceptions import WorkflowError  # noqa: F401
+from snakemake_interface_common.settings import SettingsEnumBase
+
+
+# The mountpoint for the Snakemake working directory inside the container.
+SNAKEMAKE_MOUNTPOINT = "/mnt/snakemake"
+
+
+# ContainerType is an enum that defines the different container types we support.
+# If adding new ones, make sure the choice is the same as the command name.
+class Runtime(SettingsEnumBase):
+    UDOCKER = 0
+    PODMAN = 1
+
+
+@dataclass
+class Settings(SoftwareDeploymentSettingsBase):
+    runtime: Runtime = field(
+        default=Runtime.UDOCKER,
+        metadata={
+            "help": "Container kind (udocker by default)",
+            "env_var": False,
+            "required": False,
+        },
+    )
+
+
+@dataclass
+class EnvSpec(EnvSpecBase):
+    # TODO: when integrating this plugin, image_uri should be populated from the container keyword (via whatever mechanism is exposing)
+    # the plugin to the software deployment registry.
+    image_uri: str
+
+    @classmethod
+    def identity_attributes(cls) -> Iterable[str]:
+        return ["image_uri"]
+
+    @classmethod
+    def source_path_attributes(cls) -> Iterable[str]:
+        return ()
+
+    def __str__(self) -> str:
+        """Return a string representation of the environment spec."""
+        return self.image_uri
+
+
+# All errors should be wrapped with snakemake-interface-common.errors.WorkflowError
+class Env(EnvBase):
+    # image_repo is the de-referenced repository from where the image was obtained
+    image_repo: str
+    settings: Settings  # type: ignore
+    spec: EnvSpec  # type: ignore
+
+    # image_hash is a hash of the image that can be used to identify it
+    # TODO: populate it *after* fetching/execution
+    image_hash: str
+
+    def __post_init__(self) -> None:
+        self.check()
+
+    # The decorator ensures that the decorated method is only called once
+    # in case multiple environments of the same kind are created.
+    @EnvBase.once
+    def check(self) -> None:
+        self._check_service()
+
+    def _check_service(self) -> None:
+        if self.spec.image_uri == "":
+            raise WorkflowError("Image URI is empty")
+
+        # TODO: if we don't get the tag, we should assume :latest
+
+        if self.settings.runtime not in Runtime.all():
+            raise WorkflowError("Invalid container kind")
+
+        # this assumes that the choices are the same as the command names. If
+        # this is not the case, we need to add a mapping.
+        self._check_executable()
+
+    def _check_executable(self) -> None:
+        cmd = self.settings.runtime.item_to_choice()
+        if which(cmd) is None:
+            raise WorkflowError(f"{cmd} is not available in PATH")
+
+    def decorate_shellcmd(self, cmd: str) -> str:
+        # TODO pass more options here (extra mount volumes, user etc)
+        containercache = os.path.join(
+            SNAKEMAKE_MOUNTPOINT, ".cache/snakemake/source-cache"
+        )
+
+        decorated_cmd = (
+            f"{self.settings.runtime} run"
+            " --rm"  # Remove container after execution
+            f" -e HOME={SNAKEMAKE_MOUNTPOINT!r}"  # Set HOME to working directory
+            f" -w {SNAKEMAKE_MOUNTPOINT!r}"  # Working directory inside container
+            f" -v {getcwd()!r}:{SNAKEMAKE_MOUNTPOINT!r}"  # Mount host directory to container
+            f" -v {str(self.source_cache)!r}:{containercache!r}"  # Mount host cache to container
+            f" {self.spec.image_uri}"  # Container image
+            " /bin/sh"  # Shell executable
+            f" -c {shlex.quote(cmd)}"  # The command to execute
+        )
+
+        return decorated_cmd
+
+    def record_hash(self, hash_object) -> None:
+        # Update given hash such that it changes whenever the environment
+        # could potentially contain a different set of software (in terms of versions or
+        # packages). Use self.spec (containing the corresponding EnvSpec object)
+        # to determine the hash.
+        hash_object.update(...)
+
+    def report_software(self) -> Iterable[SoftwareReport]:
+        # Report the software contained in the environment. This should be a list of
+        # snakemake_interface_software_deployment_plugins.SoftwareReport data class.
+        # Use SoftwareReport.is_secondary = True if the software is just some
+        # less important technical dependency. This allows Snakemake's report to
+        # hide those for clarity. In case of containers, it is also valid to
+        # return the container URI as a "software".
+        # Return an empty tuple () if no software can be reported.
+        # TODO: implement.
+        # Get container URI + hash (assuming we've already executd and fetched the image,
+        # so that we can get the hash for the image plus the tag)
+        return ()

snakemake_software_deployment_plugin_container-0.1.0.dist-info/METADATA

@@ -0,0 +1,42 @@
+Metadata-Version: 2.4
+Name: snakemake-software-deployment-plugin-container
+Version: 0.1.0
+Project-URL: repository, https://github.com/snakemake/snakemake-software-deployment-plugin-container
+Project-URL: documentation, https://snakemake.github.io/snakemake-plugin-catalog/plugins/software-deployment/container.html
+Author-email: Ben Carrillo <ben.uzh@pm.me>, Johannes Köster <johannes.koester@uni-due.de>
+License-File: LICENSE
+Requires-Python: <4.0,>=3.11
+Requires-Dist: snakemake-interface-common<2.0.0,>=1.17.4
+Requires-Dist: snakemake-interface-software-deployment-plugins<1.0,>=0.9.1
+Requires-Dist: udocker<2.0.0,>=1.3.17
+Description-Content-Type: text/markdown
+
+# snakemake-software-deployment-plugin-container
+
+A generic container plugin implementing snakemake's software-deployment interface.
+
+* It executes the given commands within a rootless container.
+* It currently supports both `udocker` and  `podman`.
+
+## Usage
+
+The `kind` parameter specifies valid values for the container runtime to use.
+
+The `container` directive (should be) used to specify the container image to use
+for the software deployment. This string should be a valid container image name,
+including the tag; e.g., `biocontainers/example:1.0`.
+
+By default, the plugin will attemtp to use 'latest' tag if no tag is provided.
+However, be aware that some registries may not support this, for [good
+reasons](https://github.com/BioContainers/containers/issues/297#issuecomment-439055879)
+having to do with reproducibility. So, it's a good idea to specify a tag.
+
+## Status
+
+- Work in progress. The plugin conforms to the current software-deployment interface specification, and it has passing tests.
+- Will revisit when further work is done in snakemake core to allow a more reusable integration of deployment plugins.
+
+## TODO
+
+- [ ] Add support for apptainer
+- [ ] Implement repot_sofware method with container URI *and* the resolved hash of the image.

snakemake_software_deployment_plugin_container-0.1.0.dist-info/RECORD

@@ -0,0 +1,5 @@
+snakemake_software_deployment_plugin_container/__init__.py,sha256=PA7_ScZwH3kjlB6ebA3g5_FFs86TwzfNXrDNOGMEdAA,5394
+snakemake_software_deployment_plugin_container-0.1.0.dist-info/METADATA,sha256=YY0VeImLyFkBAn0jb8yFsSdBeAQZIhYEr5st2mtrLkg,1930
+snakemake_software_deployment_plugin_container-0.1.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+snakemake_software_deployment_plugin_container-0.1.0.dist-info/licenses/LICENSE,sha256=pj54hC8EVqRRIr6bzQlgqnB-cyNUsCIDXLmCZ4xhA7E,1064
+snakemake_software_deployment_plugin_container-0.1.0.dist-info/RECORD,,

snakemake_software_deployment_plugin_container-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.28.0
+Root-Is-Purelib: true
+Tag: py3-none-any

snakemake_software_deployment_plugin_container-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 btraven
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.