flamapy-fw 2.6.0.dev5__tar.gz → 2.6.0.dev11__tar.gz

{flamapy_fw-2.6.0.dev5/flamapy_fw.egg-info → flamapy_fw-2.6.0.dev11}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: flamapy-fw
-Version: 2.6.0.dev5
+Version: 2.6.0.dev11
 Summary: Flamapy is a Python-based AAFM framework that takes into consideration previous AAFM tool designs and enables multi-solver and multi-metamodel support for the integration of AAFM tooling on the Python ecosystem.
 Author-email: Flamapy <flamapy@us.es>
 License-Expression: GPL-3.0-or-later

{flamapy_fw-2.6.0.dev5 → flamapy_fw-2.6.0.dev11}/flamapy/core/discover.py

@@ -11,6 +11,7 @@ from flamapy.core.exceptions import TransformationNotFound
 from flamapy.core.exceptions import ConfigurationNotFound
 from flamapy.core.models import VariabilityModel
 from flamapy.core.operations import Operation
+from flamapy.core.operations.descriptor import OperationDescriptor, collect_descriptors
 from flamapy.core.plugins import Operations, Plugin, Plugins
 from flamapy.core.transformations import Transformation
 from flamapy.core.transformations.text_to_model import TextToModel
@@ -104,6 +105,13 @@ class DiscoverMetamodels:
 
         return operations
 
+    def available_operations(self) -> dict[str, OperationDescriptor]:
+        """Facade descriptors of every discovered operation that declares one, keyed by public name.
+
+        This is the single source the facade, CLI and REST derive their operation surface from.
+        """
+        return collect_descriptors(self.get_operations())
+
     def get_transformations(self) -> list[Type[Transformation]]:
         """Get transformations for all modules"""
         transformations: list[Type[Transformation]] = []

{flamapy_fw-2.6.0.dev5 → flamapy_fw-2.6.0.dev11}/flamapy/core/operations/__init__.py

@@ -21,6 +21,7 @@ from .attribute_optimization import (  # pylint: disable=cyclic-import
     AttributeOptimization,
     OptimizationGoal,
 )
+from .descriptor import Input, OperationDescriptor, collect_descriptors
 
 __all__ = [
     "AtomicSets",
@@ -37,11 +38,14 @@ __all__ = [
     "EstimatedConfigurationsNumber",
     "FalseOptionalFeatures",
     "Filter",
+    "Input",
     "Metrics",
     "Operation",
+    "OperationDescriptor",
     "OptimizationGoal",
     "Sampling",
     "Satisfiable",
     "SatisfiableConfiguration",
     "Variability",
+    "collect_descriptors",
 ]

flamapy_fw-2.6.0.dev11/flamapy/core/operations/attribute_optimization.py

@@ -0,0 +1,68 @@
+from abc import abstractmethod
+from enum import Enum
+from typing import Any
+
+from flamapy.core.operations import Operation
+from flamapy.core.operations.descriptor import OperationDescriptor, Input
+
+
+class OptimizationGoal(Enum):
+    MAXIMIZE = 'Maximize'
+    MINIMIZE = 'Minimize'
+
+
+def _attribute_optimization_inputs(operation: Any, facade: Any, kwargs: dict[str, Any]) -> None:
+    objectives = kwargs['objectives']
+    if isinstance(objectives, str):
+        attributes = {objectives: OptimizationGoal.MINIMIZE}
+    else:
+        attributes = {
+            name: (OptimizationGoal.MINIMIZE if str(goal).lower().startswith('min')
+                   else OptimizationGoal.MAXIMIZE)
+            for name, goal in dict(objectives).items()
+        }
+    operation.set_attributes(attributes)
+
+
+def _attribute_optimization_result(result: Any) -> Any:
+    # z3 returns (configuration, values) tuples; sat returns bare configurations.
+    return [item[0] if isinstance(item, tuple) else item for item in result]
+
+
+class AttributeOptimization(Operation):
+    """Return the configuration(s) that optimize the given numeric feature attribute(s).
+
+    Attributes are identified by name and mapped to an :class:`OptimizationGoal`. The
+    objective for each attribute is the sum of its values over the selected features.
+    """
+
+    facade = OperationDescriptor(
+        doc=(
+            'Returns the configuration(s) that optimize one or more numeric feature\n'
+            'attributes.\n'
+            '\n'
+            '``objectives`` is either a single attribute name (defaults to minimizing it)\n'
+            'or a mapping ``{attribute_name: "Minimize"|"Maximize"}``. ``backend`` selects\n'
+            'the plugin: "sat" performs single-objective MaxSAT optimization; "z3"\n'
+            'additionally supports typed attributes and multi-objective (Pareto)\n'
+            'optimization. Defaults to "sat".'
+        ),
+        returns='Union[None, List[Configuration]]',
+        name='attribute_optimization', operation='AttributeOptimization', default_backend='sat',
+        selectable_backend=True,
+        inputs=(Input('objectives', Any, required=True),),
+        input_adapter=_attribute_optimization_inputs,
+        result_adapter=_attribute_optimization_result,
+    )
+
+    @abstractmethod
+    def __init__(self) -> None:
+        pass
+
+    @abstractmethod
+    def set_attributes(self, attributes: dict[str, OptimizationGoal]) -> None:
+        """Set the attributes to optimize as a mapping ``{attribute_name: OptimizationGoal}``."""
+
+    @abstractmethod
+    def optimize(self) -> list[Any]:
+        """Return the optimal configuration(s)."""

flamapy_fw-2.6.0.dev11/flamapy/core/operations/configurations.py

@@ -0,0 +1,29 @@
+from abc import abstractmethod
+
+from flamapy.core.operations import Operation
+from flamapy.core.operations.descriptor import OperationDescriptor
+from flamapy.metamodels.configuration_metamodel.models.configuration import Configuration
+
+
+class Configurations(Operation):
+    facade = OperationDescriptor(
+        doc=(
+            'These are the individual outcomes that can be produced from a feature model.\n'
+            'Each product is a combination of features that satisfies all the constraints\n'
+            'and dependencies in the feature model.\n'
+            '\n'
+            '``backend`` selects the analysis plugin ("sat", "bdd" or "z3"); defaults to\n'
+            'bdd.'
+        ),
+        returns='Union[None, List[Configuration]]',
+        name='configurations', operation='Configurations', default_backend='bdd',
+        selectable_backend=True,
+    )
+
+    @abstractmethod
+    def __init__(self) -> None:
+        pass
+
+    @abstractmethod
+    def get_configurations(self) -> list[Configuration]:
+        pass

flamapy_fw-2.6.0.dev11/flamapy/core/operations/configurations_number.py

@@ -0,0 +1,30 @@
+from abc import abstractmethod
+
+from flamapy.core.operations import Operation
+from flamapy.core.operations.descriptor import OperationDescriptor
+
+
+class ConfigurationsNumber(Operation):
+    facade = OperationDescriptor(
+        doc=(
+            'This is the total number of different full configurations that can be produced\n'
+            "from a feature model. It's calculated by considering all possible combinations\n"
+            'of features, taking into account the constraints and dependencies between\n'
+            'features.\n'
+            '\n'
+            '``backend`` selects the analysis plugin ("sat", "bdd", "z3", or "sharpsat" for\n'
+            'a scalable approximate count via the optional flamapy-sharpsat plugin);\n'
+            'defaults to bdd.'
+        ),
+        returns='Union[None, int]',
+        name='configurations_number', operation='ConfigurationsNumber', default_backend='bdd',
+        selectable_backend=True,
+    )
+
+    @abstractmethod
+    def __init__(self) -> None:
+        pass
+
+    @abstractmethod
+    def get_configurations_number(self) -> int:
+        pass

flamapy_fw-2.6.0.dev11/flamapy/core/operations/core_features.py

@@ -0,0 +1,29 @@
+from abc import abstractmethod
+
+from flamapy.core.operations import Operation
+from flamapy.core.operations.descriptor import OperationDescriptor
+from flamapy.core.models.variability_model import VariabilityElement
+
+
+class CoreFeatures(Operation):
+    facade = OperationDescriptor(
+        doc=(
+            'These are the features that are present in all products of a product line. In\n'
+            'a feature model, they are the features that are mandatory and not optional.\n'
+            'Core features define the commonality among all products in a product line.\n'
+            '\n'
+            '``backend`` selects the analysis plugin ("sat", "bdd" or "z3"); defaults to\n'
+            'sat.'
+        ),
+        returns='Union[None, List[str]]',
+        name='core_features', operation='CoreFeatures', default_backend='sat',
+        selectable_backend=True,
+    )
+
+    @abstractmethod
+    def __init__(self) -> None:
+        pass
+
+    @abstractmethod
+    def get_core_features(self) -> list[VariabilityElement]:
+        pass

flamapy_fw-2.6.0.dev11/flamapy/core/operations/dead_features.py

@@ -0,0 +1,29 @@
+from abc import abstractmethod
+
+from flamapy.core.operations import Operation
+from flamapy.core.operations.descriptor import OperationDescriptor
+from flamapy.core.models.variability_model import VariabilityElement
+
+
+class DeadFeatures(Operation):
+    facade = OperationDescriptor(
+        doc=(
+            'These are features that, due to the constraints and dependencies in the\n'
+            'feature model, cannot be included in any valid product. Dead features are\n'
+            'usually a sign of an error in the feature model.\n'
+            '\n'
+            '``backend`` selects the analysis plugin ("sat", "bdd" or "z3"); defaults to\n'
+            'sat.'
+        ),
+        returns='Union[None, List[str]]',
+        name='dead_features', operation='DeadFeatures', default_backend='sat',
+        selectable_backend=True,
+    )
+
+    @abstractmethod
+    def __init__(self) -> None:
+        pass
+
+    @abstractmethod
+    def get_dead_features(self) -> list[VariabilityElement]:
+        pass

flamapy_fw-2.6.0.dev11/flamapy/core/operations/descriptor.py

@@ -0,0 +1,61 @@
+"""Self-describing metadata for operations, so the facade/CLI/REST can be *derived* from the
+installed operations instead of hand-written.
+
+An operation interface (or a bespoke concrete operation) declares a class attribute ``facade`` of
+type :class:`OperationDescriptor`. It states the operation's stable public name, which backend it
+runs on, its inputs (and how to wire them), and optional input/result adapters for the few
+operations whose facade method is not a plain ``set params -> execute``. Concrete backend
+implementations inherit the descriptor from their interface, so there is exactly one descriptor
+per *logical* operation.
+"""
+from dataclasses import dataclass
+from typing import Any, Callable, Iterable, Optional
+
+
+@dataclass(frozen=True)
+class Input:
+    """One input of a facade operation and how to feed it to the underlying operation."""
+
+    name: str
+    type: Any = str                   # a type or typing special form (e.g. Any), for CLI/REST
+    default: Any = None
+    required: bool = False
+    setter: Optional[str] = None      # operation setter for the value, e.g. 'set_sample_size'
+    kind: str = 'scalar'              # 'scalar' | 'configuration' | 'file' (CLI/REST marshalling)
+
+
+@dataclass(frozen=True)
+class OperationDescriptor:
+    """Everything the facade/CLI/REST need to expose an operation without hand-written code."""
+
+    name: str                                     # stable public (facade/CLI/REST) name
+    operation: str                                # name passed to DiscoverMetamodels.use_operation
+    kind: str = 'operation'                       # 'operation' | 'producer' | 'transformer'
+    default_backend: Optional[str] = None         # None => runs directly on the feature model
+    backends: Optional[tuple[str, ...]] = None    # allowed backends (None => any implementer)
+    selectable_backend: bool = False              # facade exposes a backend= kwarg (else fixed)
+    inputs: tuple[Input, ...] = ()
+    # For the ~12 non-uniform methods: custom wiring / result reshaping. When absent, the generic
+    # "call each Input.setter, then execute, then get_result" path is used.
+    input_adapter: Optional[Callable[..., Any]] = None
+    result_adapter: Optional[Callable[[Any], Any]] = None
+    doc: str = ''
+    returns: str = 'Any'                          # return annotation (source text) for the stub
+
+    @property
+    def needs_backend(self) -> bool:
+        return self.default_backend is not None
+
+
+def collect_descriptors(operations: Iterable[type]) -> dict[str, OperationDescriptor]:
+    """Collect the ``facade`` descriptors from a set of operation classes, keyed by public name.
+
+    Concrete backend operations inherit their interface's descriptor, so several classes may yield
+    the same descriptor; they are de-duplicated by ``descriptor.name`` (first one wins).
+    """
+    descriptors: dict[str, OperationDescriptor] = {}
+    for operation in operations:
+        descriptor = getattr(operation, 'facade', None)
+        if isinstance(descriptor, OperationDescriptor):
+            descriptors.setdefault(descriptor.name, descriptor)
+    return descriptors

flamapy_fw-2.6.0.dev11/flamapy/core/operations/false_optional_features.py

@@ -0,0 +1,33 @@
+from abc import abstractmethod
+
+from flamapy.core.operations import Operation
+from flamapy.core.operations.descriptor import OperationDescriptor
+from flamapy.core.models.variability_model import VariabilityElement
+
+
+class FalseOptionalFeatures(Operation):
+    """A feature is defined as `false optional` if the selection of its parent makes the feature
+    itself selected as well, although it is defined as optional and not mandatory.
+
+    A feature in a group can be also `false optional`.
+    In general, false optional features should be marked as mandatory for maintainability purposes.
+    """
+
+    facade = OperationDescriptor(
+        doc=(
+            'These are features that appear to be optional in the feature model, but due to\n'
+            'the constraints and dependencies, must be included in every valid product.\n'
+            'Like dead features, false optional features are usually a sign of an error in\n'
+            'the feature model.\n'
+            '\n'
+            '``backend`` selects the analysis plugin ("sat", "bdd" or "z3"); defaults to\n'
+            'sat.'
+        ),
+        returns='Union[None, List[str]]',
+        name='false_optional_features', operation='FalseOptionalFeatures', default_backend='sat',
+        selectable_backend=True,
+    )
+
+    @abstractmethod
+    def get_false_optional_features(self) -> list[VariabilityElement]:
+        pass

{flamapy_fw-2.6.0.dev5 → flamapy_fw-2.6.0.dev11}/flamapy/core/operations/sampling.py

@@ -2,6 +2,7 @@ from abc import abstractmethod
 
 from flamapy.metamodels.configuration_metamodel.models.configuration import Configuration
 from flamapy.core.operations import Operation
+from flamapy.core.operations.descriptor import OperationDescriptor, Input
 
 
 class Sampling(Operation):
@@ -9,6 +10,24 @@ class Sampling(Operation):
     (or configurations) from within a variability model.
     """
 
+    facade = OperationDescriptor(
+        doc=(
+            'Returns a random sample of valid configurations of the given size. When\n'
+            'with_replacement is True, the same configuration may appear more than once.\n'
+            '\n'
+            '``backend`` selects the analysis plugin; defaults to bdd. sat and bdd\n'
+            'implement (deterministic/enumerating) sampling; "sharpsat" provides almost-\n'
+            'uniform sampling via the optional flamapy-sharpsat plugin.'
+        ),
+        returns='Union[None, List[Configuration]]',
+        name='sampling', operation='Sampling', default_backend='bdd',
+        selectable_backend=True,
+        inputs=(
+            Input('size', int, required=True, setter='set_sample_size'),
+            Input('with_replacement', bool, default=False, setter='set_with_replacement'),
+        ),
+    )
+
     @abstractmethod
     def __init__(self) -> None:
         pass

flamapy_fw-2.6.0.dev11/flamapy/core/operations/satisfiable.py

@@ -0,0 +1,28 @@
+from abc import abstractmethod
+
+from flamapy.core.operations import Operation
+from flamapy.core.operations.descriptor import OperationDescriptor
+
+
+class Satisfiable(Operation):
+    facade = OperationDescriptor(
+        doc=(
+            'In the context of feature models, this usually refers to whether the feature\n'
+            'model itself satisfies all the constraints and dependencies. A a valid feature\n'
+            'model is one that does encodes at least a single valid product.\n'
+            '\n'
+            '``backend`` selects the analysis plugin ("sat", "bdd" or "z3"); defaults to\n'
+            'sat.'
+        ),
+        returns='Union[None, bool]',
+        name='satisfiable', operation='Satisfiable', default_backend='sat',
+        selectable_backend=True,
+    )
+
+    @abstractmethod
+    def __init__(self) -> None:
+        pass
+
+    @abstractmethod
+    def is_satisfiable(self) -> bool:
+        pass

flamapy_fw-2.6.0.dev11/flamapy/core/operations/satisfiable_configuration.py

@@ -0,0 +1,47 @@
+from abc import abstractmethod
+from typing import Any
+
+from flamapy.metamodels.configuration_metamodel.models.configuration import Configuration
+from flamapy.core.operations import Operation
+from flamapy.core.operations.descriptor import OperationDescriptor, Input
+
+
+def _satisfiable_configuration_inputs(operation: Any, facade: Any, kwargs: dict[str, Any]) -> None:
+    configuration = facade._as_configuration(kwargs['configuration_path'])
+    configuration.is_full = bool(kwargs.get('full_configuration', False))
+    operation.set_configuration(configuration)
+
+
+class SatisfiableConfiguration(Operation):
+    facade = OperationDescriptor(
+        doc=(
+            'This is a product that is produced from a valid configuration of features. A\n'
+            'valid product satisfies all the constraints and dependencies in the feature\n'
+            'model.\n'
+            '\n'
+            '``configuration_path`` accepts a configuration file path, a ``{feature:\n'
+            'value}`` mapping, or a Configuration object. ``backend`` selects the analysis\n'
+            'plugin ("sat", "bdd" or "z3"); defaults to sat.'
+        ),
+        returns='Union[None, bool]',
+        name='satisfiable_configuration', operation='SatisfiableConfiguration',
+        default_backend='sat', selectable_backend=True,
+        inputs=(
+            Input('configuration_path', str, required=True, kind='configuration',
+                  setter='set_configuration'),
+            Input('full_configuration', bool, default=False),
+        ),
+        input_adapter=_satisfiable_configuration_inputs,
+    )
+
+    @abstractmethod
+    def __init__(self) -> None:
+        pass
+
+    @abstractmethod
+    def set_configuration(self, configuration: Configuration) -> None:
+        pass
+
+    @abstractmethod
+    def is_satisfiable(self) -> bool:
+        pass

{flamapy_fw-2.6.0.dev5 → flamapy_fw-2.6.0.dev11/flamapy_fw.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: flamapy-fw
-Version: 2.6.0.dev5
+Version: 2.6.0.dev11
 Summary: Flamapy is a Python-based AAFM framework that takes into consideration previous AAFM tool designs and enables multi-solver and multi-metamodel support for the integration of AAFM tooling on the Python ecosystem.
 Author-email: Flamapy <flamapy@us.es>
 License-Expression: GPL-3.0-or-later

{flamapy_fw-2.6.0.dev5 → flamapy_fw-2.6.0.dev11}/flamapy_fw.egg-info/SOURCES.txt

@@ -22,6 +22,7 @@ flamapy/core/operations/configurations_number.py
 flamapy/core/operations/core_features.py
 flamapy/core/operations/count_leafs.py
 flamapy/core/operations/dead_features.py
+flamapy/core/operations/descriptor.py
 flamapy/core/operations/error_detection.py
 flamapy/core/operations/error_diagnosis.py
 flamapy/core/operations/estimated_configurations_number.py

{flamapy_fw-2.6.0.dev5 → flamapy_fw-2.6.0.dev11}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "flamapy-fw"
-version = "2.6.0.dev5"
+version = "2.6.0.dev11"
 description = "Flamapy is a Python-based AAFM framework that takes into consideration previous AAFM tool designs and enables multi-solver and multi-metamodel support for the integration of AAFM tooling on the Python ecosystem."
 readme = "README.md"
 license = "GPL-3.0-or-later"

flamapy_fw-2.6.0.dev5/flamapy/core/operations/attribute_optimization.py

@@ -1,30 +0,0 @@
-from abc import abstractmethod
-from enum import Enum
-from typing import Any
-
-from flamapy.core.operations import Operation
-
-
-class OptimizationGoal(Enum):
-    MAXIMIZE = 'Maximize'
-    MINIMIZE = 'Minimize'
-
-
-class AttributeOptimization(Operation):
-    """Return the configuration(s) that optimize the given numeric feature attribute(s).
-
-    Attributes are identified by name and mapped to an :class:`OptimizationGoal`. The
-    objective for each attribute is the sum of its values over the selected features.
-    """
-
-    @abstractmethod
-    def __init__(self) -> None:
-        pass
-
-    @abstractmethod
-    def set_attributes(self, attributes: dict[str, OptimizationGoal]) -> None:
-        """Set the attributes to optimize as a mapping ``{attribute_name: OptimizationGoal}``."""
-
-    @abstractmethod
-    def optimize(self) -> list[Any]:
-        """Return the optimal configuration(s)."""

flamapy_fw-2.6.0.dev5/flamapy/core/operations/configurations.py

@@ -1,14 +0,0 @@
-from abc import abstractmethod
-
-from flamapy.core.operations import Operation
-from flamapy.metamodels.configuration_metamodel.models.configuration import Configuration
-
-
-class Configurations(Operation):
-    @abstractmethod
-    def __init__(self) -> None:
-        pass
-
-    @abstractmethod
-    def get_configurations(self) -> list[Configuration]:
-        pass

flamapy_fw-2.6.0.dev5/flamapy/core/operations/configurations_number.py

@@ -1,13 +0,0 @@
-from abc import abstractmethod
-
-from flamapy.core.operations import Operation
-
-
-class ConfigurationsNumber(Operation):
-    @abstractmethod
-    def __init__(self) -> None:
-        pass
-
-    @abstractmethod
-    def get_configurations_number(self) -> int:
-        pass

flamapy_fw-2.6.0.dev5/flamapy/core/operations/core_features.py

@@ -1,14 +0,0 @@
-from abc import abstractmethod
-
-from flamapy.core.operations import Operation
-from flamapy.core.models.variability_model import VariabilityElement
-
-
-class CoreFeatures(Operation):
-    @abstractmethod
-    def __init__(self) -> None:
-        pass
-
-    @abstractmethod
-    def get_core_features(self) -> list[VariabilityElement]:
-        pass

flamapy_fw-2.6.0.dev5/flamapy/core/operations/dead_features.py

@@ -1,14 +0,0 @@
-from abc import abstractmethod
-
-from flamapy.core.operations import Operation
-from flamapy.core.models.variability_model import VariabilityElement
-
-
-class DeadFeatures(Operation):
-    @abstractmethod
-    def __init__(self) -> None:
-        pass
-
-    @abstractmethod
-    def get_dead_features(self) -> list[VariabilityElement]:
-        pass

flamapy_fw-2.6.0.dev5/flamapy/core/operations/false_optional_features.py

@@ -1,17 +0,0 @@
-from abc import abstractmethod
-
-from flamapy.core.operations import Operation
-from flamapy.core.models.variability_model import VariabilityElement
-
-
-class FalseOptionalFeatures(Operation):
-    """A feature is defined as `false optional` if the selection of its parent makes the feature
-    itself selected as well, although it is defined as optional and not mandatory.
-
-    A feature in a group can be also `false optional`.
-    In general, false optional features should be marked as mandatory for maintainability purposes.
-    """
-
-    @abstractmethod
-    def get_false_optional_features(self) -> list[VariabilityElement]:
-        pass

flamapy_fw-2.6.0.dev5/flamapy/core/operations/satisfiable.py

@@ -1,13 +0,0 @@
-from abc import abstractmethod
-
-from flamapy.core.operations import Operation
-
-
-class Satisfiable(Operation):
-    @abstractmethod
-    def __init__(self) -> None:
-        pass
-
-    @abstractmethod
-    def is_satisfiable(self) -> bool:
-        pass

flamapy_fw-2.6.0.dev5/flamapy/core/operations/satisfiable_configuration.py

@@ -1,18 +0,0 @@
-from abc import abstractmethod
-
-from flamapy.metamodels.configuration_metamodel.models.configuration import Configuration
-from flamapy.core.operations import Operation
-
-
-class SatisfiableConfiguration(Operation):
-    @abstractmethod
-    def __init__(self) -> None:
-        pass
-
-    @abstractmethod
-    def set_configuration(self, configuration: Configuration) -> None:
-        pass
-
-    @abstractmethod
-    def is_satisfiable(self) -> bool:
-        pass