snakemake-interface-software-deployment-plugins 0.2.3__tar.gz → 0.4.0__tar.gz

{snakemake_interface_software_deployment_plugins-0.2.3 → snakemake_interface_software_deployment_plugins-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: snakemake-interface-software-deployment-plugins
-Version: 0.2.3
+Version: 0.4.0
 Summary: This package provides a stable interface for interactions between Snakemake and its software deployment plugins.
 License: MIT
 Author: Johannes Köster

{snakemake_interface_software_deployment_plugins-0.2.3 → snakemake_interface_software_deployment_plugins-0.4.0}/pyproject.toml

@@ -5,7 +5,7 @@ license = "MIT"
 name = "snakemake-interface-software-deployment-plugins"
 packages = [{include = "snakemake_interface_software_deployment_plugins"}]
 readme = "README.md"
-version = "0.2.3"
+version = "0.4.0"
 
 [tool.poetry.dependencies]
 argparse-dataclass = "^2.0.0"
@@ -17,6 +17,7 @@ coverage = {extras = ["toml"], version = "^6.3.1"}
 flake8-bugbear = "^22.1.11"
 pytest = "^7.0"
 ruff = "^0.9.9"
+snakemake-software-deployment-plugin-envmodules = "^0.1.2"
 
 [tool.coverage.run]
 omit = [".*", "*/site-packages/*"]

{snakemake_interface_software_deployment_plugins-0.2.3 → snakemake_interface_software_deployment_plugins-0.4.0}/snakemake_interface_software_deployment_plugins/__init__.py

@@ -5,11 +5,10 @@ __license__ = "MIT"
 
 from abc import ABC, abstractmethod
 from copy import copy
-from dataclasses import dataclass, field, fields
+from dataclasses import dataclass, field
 import hashlib
 from pathlib import Path
-import sys
-from typing import Any, ClassVar, Dict, Optional, Tuple, Type
+from typing import Any, ClassVar, Dict, Iterable, Optional, Self, Tuple, Type
 import subprocess as sp
 
 from snakemake_interface_software_deployment_plugins.settings import (
@@ -17,28 +16,91 @@ from snakemake_interface_software_deployment_plugins.settings import (
 )
 
 
-_MANAGED_FIELDS = {
-    "settings",
-    "_managed_hash_store",
-    "_managed_deployment_hash_store",
-    "_obj_hash",
-}
+@dataclass
+class SoftwareReport:
+    name: str
+    version: Optional[str] = None
+    is_secondary: bool = False
 
 
-@dataclass
 class EnvSpecBase(ABC):
-    within: Optional["EnvSpecBase"]
-    fallback: Optional["EnvSpecBase"]
+    def __init__(self):
+        self.within: Optional["EnvSpecBase"] = None
+        self.fallback: Optional["EnvSpecBase"] = None
+        self.kind: str = self.__class__.__module__.common_settings.provides
+        self._obj_hash: Optional[int] = None
 
     @classmethod
     def env_cls(cls):
-        return sys.modules[__name__].EnvBase
+        return cls.__module__.EnvBase
+
+    @abstractmethod
+    def identity_attributes(self) -> Iterable[str]:
+        """Yield the attributes of the subclass that uniquely identify the
+        environment spec. These are used for hashing and equality comparison.
+        """
+        ...
+
+    @abstractmethod
+    def source_path_attributes(self) -> Iterable[str]:
+        """Return iterable of attributes of the subclass that represent paths that are
+        supposed to be interpreted as being relative to the defining rule.
+
+        For example, this would be attributes pointing to conda environment files.
+        """
+        ...
+
+    def has_source_paths(self) -> bool:
+        if any(self.source_path_attributes()):
+            return True
+        if self.within is not None and self.within.has_source_paths():
+            return True
+        if self.fallback is not None and self.fallback.has_source_paths():
+            return True
+        return False
+
+    def modify_source_paths(self, modify_func) -> Self:
+        if self.has_source_paths():
+            self_or_copied = copy(self)
+        else:
+            return self
+        for attr in self_or_copied.source_path_attributes():
+            setattr(self_or_copied, attr, modify_func(getattr(self_or_copied, attr)))
+
+        if self_or_copied.within is not None:
+            self_or_copied.within = self_or_copied.within.modify_source_paths(
+                modify_func
+            )
+
+        if self_or_copied.fallback is not None:
+            self_or_copied.fallback = self_or_copied.fallback.modify_source_paths(
+                modify_func
+            )
+        return self_or_copied
 
     def __or__(self, other: "EnvSpecBase") -> "EnvSpecBase":
         copied = copy(self)
         copied.fallback = other
+        copied._obj_hash = None
         return copied
 
+    def managed_identity_attributes(self) -> Iterable[str]:
+        yield from self.identity_attributes()
+        yield "kind"
+        yield "within"
+        yield "fallback"
+
+    def __hash__(self) -> int:
+        return hash(
+            tuple(getattr(self, attr) for attr in self.managed_identity_attributes())
+        )
+
+    def __eq__(self, other) -> bool:
+        return self.__class__ == other.__class__ and all(
+            getattr(self, attr) == getattr(other, attr)
+            for attr in self.managed_identity_attributes()
+        )
+
 
 @dataclass
 class EnvBase:
@@ -80,9 +142,21 @@ class EnvBase:
 
     @abstractmethod
     def record_hash(self, hash_object) -> None:
-        """Update given hash object such that it changes whenever the environment
-        specified via self.spec could potentially contain a different set of
-        software (in terms of versions or packages).
+        """Update given hash object (using hash_object.update()) such that it changes
+        whenever the environment specified via self.spec could potentially contain a
+        different set of software (in terms of versions or packages).
+        """
+        ...
+
+    @abstractmethod
+    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.
         """
         ...
 
@@ -119,20 +193,14 @@ class EnvBase:
     def __hash__(self) -> int:
         # take the hash of all fields by settings, _managed_hash_store and _managed_deployment_hash_store
         if self._obj_hash is None:
-            self._obj_hash = hash(
-                tuple(
-                    getattr(self, field.name)
-                    for field in fields(self)
-                    if field.name not in _MANAGED_FIELDS
-                )
-            )
+            self._obj_hash = hash(self.hash())
         return self._obj_hash
 
     def __eq__(self, other) -> bool:
-        return self.__class__ == other.__class__ and all(
-            getattr(self, field.name) == getattr(other, field.name)
-            for field in fields(self)
-            if field.name not in _MANAGED_FIELDS
+        return (
+            self.__class__ == other.__class__
+            and self.spec == other.spec
+            and self.hash() == other.hash()
         )
 
 

{snakemake_interface_software_deployment_plugins-0.2.3 → snakemake_interface_software_deployment_plugins-0.4.0}/snakemake_interface_software_deployment_plugins/registry/__init__.py

@@ -6,6 +6,7 @@ __license__ = "MIT"
 import types
 from typing import Mapping
 from snakemake_interface_software_deployment_plugins.settings import (
+    CommonSettings,
     SoftwareDeploymentSettingsBase,
 )
 
@@ -16,7 +17,11 @@ from snakemake_interface_common.plugin_registry.attribute_types import (
 )
 from snakemake_interface_software_deployment_plugins.registry.plugin import Plugin
 from snakemake_interface_common.plugin_registry import PluginRegistryBase
-from snakemake_interface_software_deployment_plugins import EnvBase, _common as common
+from snakemake_interface_software_deployment_plugins import (
+    EnvBase,
+    EnvSpecBase,
+    _common as common,
+)
 
 
 class SoftwareDeploymentPluginRegistry(PluginRegistryBase):
@@ -30,14 +35,21 @@ class SoftwareDeploymentPluginRegistry(PluginRegistryBase):
         """Load a plugin by name."""
         return Plugin(
             _name=name,
+            common_settings=module.common_settings,
             _software_deployment_settings_cls=getattr(
                 module, "SoftwareDeploymentSettings", None
             ),
             _env_cls=module.EnvBase,
+            _env_spec_cls=module.EnvSpecBase,
         )
 
     def expected_attributes(self) -> Mapping[str, AttributeType]:
         return {
+            "common_settings": AttributeType(
+                cls=CommonSettings,
+                mode=AttributeMode.REQUIRED,
+                kind=AttributeKind.OBJECT,
+            ),
             "SoftwareDeploymentSettings": AttributeType(
                 cls=SoftwareDeploymentSettingsBase,
                 mode=AttributeMode.OPTIONAL,
@@ -48,4 +60,9 @@ class SoftwareDeploymentPluginRegistry(PluginRegistryBase):
                 mode=AttributeMode.REQUIRED,
                 kind=AttributeKind.CLASS,
             ),
+            "EnvSpec": AttributeType(
+                cls=EnvSpecBase,
+                mode=AttributeMode.REQUIRED,
+                kind=AttributeKind.CLASS,
+            ),
         }

{snakemake_interface_software_deployment_plugins-0.2.3 → snakemake_interface_software_deployment_plugins-0.4.0}/snakemake_interface_software_deployment_plugins/registry/plugin.py

@@ -7,6 +7,7 @@ from dataclasses import dataclass
 from typing import Optional, Type
 from snakemake_interface_software_deployment_plugins import EnvBase, EnvSpecBase
 from snakemake_interface_software_deployment_plugins.settings import (
+    CommonSettings,
     SoftwareDeploymentSettingsBase,
 )
 import snakemake_interface_software_deployment_plugins._common as common
@@ -16,6 +17,7 @@ from snakemake_interface_common.plugin_registry.plugin import PluginBase
 
 @dataclass
 class Plugin(PluginBase):
+    common_settings: CommonSettings
     _software_deployment_settings_cls: Optional[Type[SoftwareDeploymentSettingsBase]]
     _env_cls: Type[EnvBase]
     _env_spec_cls: Type[EnvSpecBase]

snakemake_interface_software_deployment_plugins-0.4.0/snakemake_interface_software_deployment_plugins/settings.py

@@ -0,0 +1,46 @@
+from dataclasses import dataclass
+
+
+import snakemake_interface_common.plugin_registry.plugin
+
+
+@dataclass
+class SoftwareDeploymentSettingsBase(
+    snakemake_interface_common.plugin_registry.plugin.SettingsBase
+):
+    """Base class for software deployment settings.
+
+    Software deployment plugins can define a subclass of this class,
+    named 'SoftwareDeploymentProviderSettings'.
+    """
+
+    pass
+
+
+@dataclass
+class CommonSettings:
+    """Common settings for software deployment plugins.
+
+    This class is used to define common settings for software deployment plugins.
+
+    Attributes
+    ----------
+    provides : str
+        The kind of the software environment provided (e.g. conda, container).
+        This should not return something describing the tool to provide the software
+        environment but the resulting environment itself. For example,
+        it should return "conda" instead of mamba, rattler, pixi etc., or
+        "container" instead of docker, singularity, podman, or
+        "envmodules" instead of lmod, environment-modules, etc.
+        Snakemake will ensure that the user only activates one plugin per provided
+        kind.
+    """
+
+    provides: str
+
+    def __post_init__(self):
+        if not self.provides.isidentifier():
+            raise ValueError(
+                "CommonSettings.provides must be a valid Python identifier, but "
+                f"is {self.provides}."
+            )

{snakemake_interface_software_deployment_plugins-0.2.3 → snakemake_interface_software_deployment_plugins-0.4.0}/snakemake_interface_software_deployment_plugins/tests.py

@@ -1,4 +1,5 @@
 from abc import ABC, abstractmethod
+from pathlib import Path
 from typing import Optional, Type
 import subprocess as sp
 
@@ -9,6 +10,7 @@ from snakemake_interface_software_deployment_plugins import (
     DeployableEnvBase,
     EnvBase,
     EnvSpecBase,
+    SoftwareReport,
 )
 from snakemake_interface_software_deployment_plugins.settings import (
     SoftwareDeploymentSettingsBase,
@@ -46,10 +48,10 @@ class TestSoftwareDeploymentBase(ABC):
         """
         ...
 
+    @abstractmethod
     def get_software_deployment_provider_settings(
         self,
-    ) -> Optional[SoftwareDeploymentSettingsBase]:
-        return None
+    ) -> Optional[SoftwareDeploymentSettingsBase]: ...
 
     def test_shellcmd(self, tmp_path):
         env = self._get_env(tmp_path)
@@ -83,6 +85,27 @@ class TestSoftwareDeploymentBase(ABC):
         env.archive()
         assert any((tmp_path / "{_TEST_SDM_NAME}-archive").iterdir())
 
+    def test_report_software(self, tmp_path):
+        env = self._get_env(tmp_path)
+        rep = env.report_software()
+        assert all(isinstance(s, SoftwareReport) for s in rep)
+
+    def test_identity_attributes(self):
+        spec = self.get_env_spec()
+        assert all(
+            isinstance(attr, str) and hasattr(spec, attr)
+            for attr in spec.identity_attributes()
+        )
+
+    def test_source_path_attributes(self):
+        spec = self.get_env_spec()
+        assert all(
+            isinstance(attr, str)
+            and hasattr(spec, attr)
+            and isinstance(getattr(spec, attr), (Path, str))
+            for attr in spec.source_path_attributes()
+        )
+
     def _get_env(self, tmp_path) -> EnvBase:
         env_cls = self.get_env_cls()
         spec = self.get_env_spec()

snakemake_interface_software_deployment_plugins-0.2.3/snakemake_interface_software_deployment_plugins/settings.py

@@ -1,17 +0,0 @@
-from dataclasses import dataclass
-
-
-import snakemake_interface_common.plugin_registry.plugin
-
-
-@dataclass
-class SoftwareDeploymentSettingsBase(
-    snakemake_interface_common.plugin_registry.plugin.SettingsBase
-):
-    """Base class for software deployment settings.
-
-    Software deployment plugins can define a subclass of this class,
-    named 'SoftwareDeploymentProviderSettings'.
-    """
-
-    pass