flamapy 2.6.0.dev12__py3-none-any.whl → 2.9.0.dev0__py3-none-any.whl

flamapy/commands/__init__.py

@@ -10,6 +10,7 @@ from shutil import copytree
 from typing import Any, List, Tuple, Optional, Union, get_args, get_origin
 from types import FunctionType
 
+from flamapy.core.exceptions import FlamaException
 from flamapy.interfaces.python.flamapy_feature_model import FLAMAFeatureModel
 
 # List to store registered commands and their arguments
@@ -57,7 +58,8 @@ def extract_commands(
         if name.startswith("_"):
             continue
         if getattr(method, "_facade_kind", "operation") != "operation":
-            continue  # producers/transformers return models; Python-API only for now
+            # producers/transformers return models: Python API and REST (as UVL), not the CLI
+            continue
         docstring: Optional[str] = method.__doc__
         signature = inspect.signature(method)
         # Exclude 'self' from parameters
@@ -67,6 +69,53 @@ def extract_commands(
     return commands
 
 
+@command(
+    "plan",
+    "Shows which backend the query planner would pick for an operation on a model. "
+    "The planner is opt-in: run operations with --backend auto (or FLAMAPY_BACKEND=auto) "
+    "to actually use it.",
+    ("operation", str, "Facade operation name, e.g. configurations_number"),
+    ("model_path", str, "Path to the feature model file"),
+)
+def plan_command(args):  # type: ignore
+    fm = FLAMAFeatureModel(args.model_path)
+    try:
+        chosen = fm.plan(args.operation)
+    except FlamaException as error:
+        print(f"No compatible backend: {error}")
+        return None
+    data = chosen.to_dict(fm.fm_model.get_extension())
+    print(f"operation:            {args.operation}")
+    print(f"chosen backend:       {data['plugin']} (extension '{data['backend']}')")
+    print(f"transformation chain: {' -> '.join(data['transformation_chain'])}")
+    print(f"estimated cost:       {data['estimated_cost_ms']} ms (heuristic)")
+    print(f"rationale:            {data['rationale']}")
+    if data['alternatives']:
+        print(f"alternatives:         {', '.join(data['alternatives'])}")
+    return None
+
+
+@command(
+    "cache",
+    "Inspects or clears the compilation-artifact cache (opt-in: set FLAMAPY_CACHE=1 to "
+    "cache compiled backends such as BDDs across runs).",
+    ("action", str, "'info' or 'clear'"),
+)
+def cache_command(args):  # type: ignore
+    from flamapy.core import cache as artifact_cache  # noqa: PLC0415
+
+    if args.action == "info":
+        stats = artifact_cache.info()
+        print(f"enabled:   {stats['enabled']} (set FLAMAPY_CACHE=1 to enable)")
+        print(f"directory: {stats['directory']}")
+        print(f"artifacts: {stats['artifacts']} ({stats['size_mb']} MB)")
+    elif args.action == "clear":
+        removed = artifact_cache.clear()
+        print(f"removed {removed} artifact(s)")
+    else:
+        print(f"Unknown cache action '{args.action}'; use 'info' or 'clear'.")
+
+
 @command(
     "generate_plugin",
     "Generates a new plugin skeleton to implement your custom operations. "
@@ -108,7 +157,9 @@ def generate_plugin(args):  # type: ignore
             lines = file.readlines()
         with open(copy_file, "w", encoding="utf-8") as filewrite:
             for line in lines:
-                out_line = line.replace("__NAME__", name.capitalize()).replace("__EXT__", ext)
+                out_line = (line.replace("__NAME_LOWER__", name)
+                            .replace("__NAME__", name.capitalize())
+                            .replace("__EXT__", ext))
                 filewrite.write(out_line)
 
     os.rename(
@@ -156,6 +207,12 @@ def setup_dynamic_commands(subparsers, dynamic_commands):  # type: ignore
                         default=param.default,
                         help=f"Optional {arg_type.__name__}",
                     )
+        subparser.add_argument(
+            "-v", "--verbose", action="store_true",
+            help="Also print the result's provenance (plugin, backend, exact, wall time)")
+        subparser.add_argument(
+            "--timeout", type=float, default=None, metavar="SECONDS",
+            help="Abort if the operation exceeds this wall-clock time (exit code 124)")
         subparser.set_defaults(func=method, method_name=name, parameters=parameters)
 
 
@@ -168,19 +225,66 @@ def setup_manual_commands(subparsers, manual_commands):  # type: ignore
         subparser.set_defaults(func=func)
 
 
+def _run_with_timeout(cls_instance, method_name, command_args, timeout):  # type: ignore
+    """Run the operation asynchronously and enforce the wall-clock deadline (exit 124)."""
+    from flamapy.core.exceptions import OperationTimeout  # noqa: PLC0415
+
+    try:
+        job = cls_instance.run_async(method_name, **command_args)
+        result = job.result(timeout=timeout)
+    except OperationTimeout as error:
+        print(f"Timeout: {error}", file=sys.stderr)
+        sys.exit(124)
+    except FlamaException as error:
+        print(f"Error: {error}", file=sys.stderr)
+        return None
+    cls_instance.last_result = job.envelope()
+    return result
+
+
+def _print_provenance(envelope) -> None:  # type: ignore
+    print("--- provenance ---", file=sys.stderr)
+    print(f"operation: {envelope.operation}  plugin: {envelope.plugin}  "
+          f"backend: {envelope.backend}", file=sys.stderr)
+    print(f"exact: {envelope.exact}  wall_time: {envelope.wall_time:.6f}s  "
+          f"cache_hit: {envelope.cache_hit}", file=sys.stderr)
+    if envelope.planner is not None:
+        print(f"planner: {envelope.planner}", file=sys.stderr)
+    print(f"model_hash: {envelope.model_hash}", file=sys.stderr)
+
+
+def _execute_dynamic(args: argparse.Namespace) -> None:
+    cls_instance = FLAMAFeatureModel(args.model_path)
+    method_parameters = [param.name for param in args.parameters]
+    command_args = {k: v for k, v in vars(args).items() if k in method_parameters}
+    descriptor = getattr(
+        getattr(type(cls_instance), args.method_name), "_facade_descriptor", None)
+    timeout = getattr(args, "timeout", None)
+    if timeout is not None:
+        result = _run_with_timeout(cls_instance, args.method_name, command_args, timeout)
+    elif (getattr(descriptor, "streaming", False)
+            and args.method_name == "configurations"
+            and command_args.get("backend") == "sat"):
+        # Explicitly-chosen streaming backend: print each configuration as the
+        # solver produces it (the default bdd output is unchanged).
+        for configuration in cls_instance.iter_configurations(backend="sat"):
+            print(configuration)
+        result = None
+    else:
+        method = getattr(cls_instance, args.method_name)
+        result = method(**command_args)
+    if result is not None:
+        print(result)
+    if getattr(args, "verbose", False) and cls_instance.last_result is not None:
+        _print_provenance(cls_instance.last_result)
+
+
 def execute_command(args: argparse.Namespace) -> None:
     try:
         if hasattr(args, "method_name"):
-            cls_instance = FLAMAFeatureModel(args.model_path)
-            method_parameters = [param.name for param in args.parameters]
-            command_args = {k: v for k, v in vars(args).items() if k in method_parameters}
-            method = getattr(cls_instance, args.method_name)
-            result = method(**command_args)
-            if result is not None:
-                print(result)
+            _execute_dynamic(args)
         else:
             func = args.func
-            command_args = {k: v for k, v in vars(args).items() if k != "func"}
             result = func(args)
             if result is not None:
                 print(result)

flamapy/interfaces/python/_stub.py

@@ -5,6 +5,7 @@ This module renders a ``.pyi`` stub from the same OperationDescriptors, giving a
 mypy the real signatures + return types. Run ``python -m flamapy.interfaces.python._stub`` to
 regenerate; a test asserts the shipped stub matches this output so it never drifts.
 """
+import re
 from typing import Any
 
 from flamapy.core.discover import DiscoverMetamodels
@@ -14,8 +15,10 @@ _HEADER = '''\
 # Auto-generated by flamapy.interfaces.python._stub — do not edit by hand.
 # Regenerate with: python -m flamapy.interfaces.python._stub
 from enum import Enum
-from typing import Any, Dict, List, Optional, Tuple, Union
+from typing import Any, Dict, List, Optional, Tuple, Union  # noqa: F401
 
+from flamapy.core.operations import OperationResult
+from flamapy.core.planner import Plan
 from flamapy.metamodels.configuration_metamodel.models import Configuration
 from flamapy.metamodels.fm_metamodel.models import FeatureModel
 
@@ -25,13 +28,25 @@ class Backend(str, Enum):
     BDD = ...
     Z3 = ...
     SHARPSAT = ...
+    SDD = ...
+    DNNF = ...
+    AUTO = ...
 
 
 class FLAMAFeatureModel:
     model_path: str
     fm_model: FeatureModel
     backend: Optional[Backend]
-    def __init__(self, model_path: str, backend: Optional[str] = ...) -> None: ...
+    allow_approximate: Optional[bool]
+    raise_errors: Optional[bool]
+    last_result: Optional[OperationResult[Any]]
+    def __init__(self, model_path: str, backend: Optional[str] = ...,
+                 *, allow_approximate: Optional[bool] = ...,
+                 raise_errors: Optional[bool] = ...) -> None: ...
+    def plan(self, operation: str, *, allow_approximate: Optional[bool] = ...) -> Plan: ...
+    def _plan_operation(self, operation_name: str, allow_approximate: bool = ...) -> Plan: ...
+    def run_async(self, operation: str, **kwargs: Any) -> Any: ...
+    def iter_configurations(self, backend: Optional[str] = ...) -> Any: ...
 '''
 
 
@@ -52,9 +67,16 @@ def _method_signature(descriptor: OperationDescriptor) -> str:
             params.append(f'{input_spec.name}: {annotation} = ...')
     if descriptor.selectable_backend:
         params.append('backend: Optional[str] = ...')
+        params.append('*')
+        params.append('allow_approximate: Optional[bool] = ...')
     return ', '.join(params)
 
 
+def _return_annotation(descriptor: OperationDescriptor) -> str:
+    # Descriptors spell nullable returns 'Union[None, X]'; the stub uses 'Optional[X]'.
+    return re.sub(r'^Union\[None, (.*)\]$', r'Optional[\1]', descriptor.returns)
+
+
 def render_stub(operations: 'dict[str, OperationDescriptor] | None' = None) -> str:
     if operations is None:
         operations = DiscoverMetamodels().available_operations()
@@ -64,7 +86,8 @@ def render_stub(operations: 'dict[str, OperationDescriptor] | None' = None) -> s
         if descriptor.kind == 'producer':
             lines.append('    @staticmethod')
         lines.append(
-            f'    def {name}({_method_signature(descriptor)}) -> {descriptor.returns}: ...')
+            f'    def {name}({_method_signature(descriptor)}) '
+            f'-> {_return_annotation(descriptor)}: ...')
     return '\n'.join(lines) + '\n'
 
 

flamapy/interfaces/python/flamapy_feature_model.py

@@ -10,15 +10,31 @@ per-operation or per-backend code here. Static typing is provided by a generated
 """
 import inspect
 import logging
+import os
+import threading
 from enum import Enum
-from typing import Any, Dict, Optional, Union
+from typing import Any, Dict, Iterator, Optional, Union
 
+import dataclasses
+import warnings
+
+from flamapy.core import cache as artifact_cache
 from flamapy.core.discover import DiscoverMetamodels
-from flamapy.core.exceptions import FlamaException
+from flamapy.core.exceptions import FlamaException, OperationTimeout, PluginNotFound
+from flamapy.core.execution import Interruptible, Job, default_engine, run_and_wrap
 from flamapy.core.models import VariabilityModel
-from flamapy.core.operations import OperationDescriptor
+from flamapy.core.models.language_level import LanguageLevel
+from flamapy.core.operations import (
+    OperationDescriptor,
+    OperationResult,
+    StreamingOperation,
+)
+from flamapy.core.planner import Plan, plan as plan_backend
 from flamapy.metamodels.configuration_metamodel.models import Configuration
 from flamapy.metamodels.fm_metamodel.models import FeatureModel
+from flamapy.metamodels.fm_metamodel.operations.fm_language_level import (
+    calculate_language_level,
+)
 
 logger = logging.getLogger(__name__)
 
@@ -33,12 +49,38 @@ class Backend(str, Enum):
     SAT = "sat"
     BDD = "bdd"
     Z3 = "z3"
+    # Optional backends, installed via the flamapy extras of the same name
+    # (e.g. pip install "flamapy[sharpsat]", or "flamapy[all-solvers]" for all three).
     SHARPSAT = "sharpsat"
+    SDD = "sdd"
+    DNNF = "dnnf"
+    # Opt-in: let the query planner pick the backend per operation, from the plugins'
+    # capability manifests (language level, scale, cost). Also enabled process-wide by
+    # setting FLAMAPY_BACKEND=auto. Becomes the default in flamapy 3.0.
+    AUTO = "auto"
 
 
 # Facade backend name -> fm-to-backend transformation extension (the only non-identity mapping).
 _BACKEND_ALIAS = {"sat": "pysat"}
 
+# Operations that ran on a fixed backend in 2.6 and accept ``backend=`` since 2.9. In 2.x only a
+# per-call ``backend=`` changes them: the workspace default and FLAMAPY_BACKEND do not, so code
+# that set a default backend in 2.6 keeps the same results (the default would otherwise move
+# atomic sets from the tree to SAT, or send commonality to a backend without it). 3.0 applies
+# the defaults to them like to every other selectable operation.
+_SELECTABLE_SINCE_2_9 = frozenset({'atomic_sets', 'commonality'})
+
+_TRUE_VALUES = ('1', 'true', 'yes', 'on')
+
+
+def _env_flag(name: str) -> bool:
+    return os.environ.get(name, '').strip().lower() in _TRUE_VALUES
+
+
+def _raise_errors(setting: Optional[bool]) -> bool:
+    """The model's ``raise_errors`` when set, else the FLAMAPY_RAISE_ERRORS variable."""
+    return setting if setting is not None else _env_flag('FLAMAPY_RAISE_ERRORS')
+
 
 class FLAMAFeatureModel:
     """A feature model together with the analysis operations discovered from the installed plugins.
@@ -47,18 +89,46 @@ class FLAMAFeatureModel:
     them as normal methods, e.g. ``FLAMAFeatureModel(path).satisfiable()``.
     """
 
-    def __init__(self, model_path: str, backend: Optional[str] = None) -> None:
+    def __init__(self, model_path: str, backend: Optional[str] = None, *,
+                 allow_approximate: Optional[bool] = None,
+                 raise_errors: Optional[bool] = None) -> None:
         """``model_path`` is the filesystem path to the model (UVL, FaMaXML or FeatureIDE).
 
-        ``backend`` optionally sets a workspace-wide default backend ("sat", "bdd" or "z3") for
-        every operation that supports more than one. When left as ``None`` each operation keeps its
-        historical default, so existing code behaves exactly as before.
+        ``backend`` optionally sets a workspace-wide default backend ("sat", "bdd" or "z3",
+        plus "sharpsat"/"sdd"/"dnnf" when the corresponding optional flamapy extra is
+        installed) for every operation that supports more than one. When left as ``None``
+        each operation keeps its historical default, so existing code behaves exactly as
+        before. ``atomic_sets`` and ``commonality``, selectable only since 2.9, follow just a
+        per-call ``backend=`` in 2.x.
+
+        ``allow_approximate`` lets the ``'auto'`` backend choose approximate implementations
+        (e.g. sharpsat's ApproxMC counting, or the structural core features that ignore
+        cross-tree constraints); by default the planner only picks exact ones. It has no
+        effect on other backends. ``None`` falls back to ``FLAMAPY_ALLOW_APPROXIMATE=1``; a
+        per-call ``allow_approximate=`` overrides both.
+
+        ``raise_errors`` opts into the 3.0 error contract today: a failing operation raises
+        its ``FlamaException`` instead of logging it and returning ``None``. ``None`` falls
+        back to ``FLAMAPY_RAISE_ERRORS=1``, which also applies to the producers (e.g.
+        ``generate_random_feature_model``).
+
+        Both flags are keyword-only.
         """
         self.model_path = model_path
         self.discover_metamodel = DiscoverMetamodels()
         self.fm_model = self._read(model_path)
         self.backend = Backend(backend) if backend is not None else None
+        self.allow_approximate = allow_approximate
+        self.raise_errors = raise_errors
         self._backend_models: Dict[str, VariabilityModel] = {}
+        # Provenance envelope of the last executed operation (value, plugin, backend, exact,
+        # wall time, model hash). Purely informational in 2.9; methods still return bare
+        # values. In 3.0 the envelope becomes the return type.
+        self.last_result: Optional[OperationResult] = None
+        # How the last operation's backend was chosen: None (historical default),
+        # 'explicit', or 'auto: <planner rationale>'.
+        self._last_planner: Optional[str] = None
+        self._model_language_level: Optional[LanguageLevel] = None
 
     def _read(self, model_path: str) -> FeatureModel:
         return self.discover_metamodel.use_transformation_t2m(model_path, "fm")
@@ -78,61 +148,227 @@ class FLAMAFeatureModel:
         return self.discover_metamodel.use_transformation_t2m(configuration, "configuration")
 
     def _model_for(
-        self, descriptor: OperationDescriptor, backend_arg: Optional[str]
+        self, descriptor: OperationDescriptor, backend_arg: Optional[str],
+        allow_approximate: Optional[bool] = None,
     ) -> VariabilityModel:
         """Resolve the operation's target model, lazily transforming (and caching) fm->backend.
 
-        The backend is the per-call one > workspace default > the operation's default (for
-        backend-selectable ops), or simply the fixed default. When it resolves to ``None`` (an
-        fm-level op, or a selectable op with no backend requested) the operation runs on the feature
-        model directly. Otherwise the name is mapped to a transformation extension (only
+        The backend is the per-call one > workspace default > the ``FLAMAPY_BACKEND``
+        environment variable > the operation's default (for backend-selectable ops), or
+        simply the fixed default. The value ``'auto'`` (opt-in) hands the choice to the
+        query planner. When the backend resolves to ``None`` (an fm-level op, or a
+        selectable op with no backend requested) the operation runs on the feature model
+        directly. Otherwise the name is mapped to a transformation extension (only
         ``sat -> pysat`` differs) and cached per extension.
         """
+        self._last_planner = None
+        defaults_apply = (descriptor.selectable_backend
+                          and descriptor.name not in _SELECTABLE_SINCE_2_9)
+        workspace_default = (self.backend or os.environ.get('FLAMAPY_BACKEND')
+                             if defaults_apply else None)
         if descriptor.selectable_backend:
-            resolved = backend_arg or self.backend or descriptor.default_backend
+            resolved = backend_arg or workspace_default or descriptor.default_backend
         else:
             resolved = descriptor.default_backend
         if resolved is None:
             return self.fm_model
         name = resolved.value if isinstance(resolved, Backend) else str(resolved)
+        if name == Backend.AUTO.value and descriptor.selectable_backend:
+            return self._model_via_planner(descriptor, self._approximate_allowed(allow_approximate))
+        if backend_arg or workspace_default:
+            self._last_planner = 'explicit'
         extension = _BACKEND_ALIAS.get(name, name)
+        return self._backend_model(extension)
+
+    def _backend_model(self, extension: str) -> VariabilityModel:
+        if extension == self.fm_model.get_extension():
+            return self.fm_model
         if extension not in self._backend_models:
             self._backend_models[extension] = self.discover_metamodel.use_transformation_m2m(
                 self.fm_model, extension)
         return self._backend_models[extension]
 
+    def _language_level(self) -> LanguageLevel:
+        if self._model_language_level is None:
+            self._model_language_level = calculate_language_level(self.fm_model)
+        return self._model_language_level
+
+    def _approximate_allowed(self, per_call: Optional[bool]) -> bool:
+        """Per-call flag > the model's setting > the FLAMAPY_ALLOW_APPROXIMATE variable."""
+        if per_call is not None:
+            return per_call
+        if self.allow_approximate is not None:
+            return self.allow_approximate
+        return _env_flag('FLAMAPY_ALLOW_APPROXIMATE')
+
+    def _plan_operation(self, operation_name: str, allow_approximate: bool = False) -> Plan:
+        """Ask the query planner which backend should run ``operation_name`` on this model.
+
+        The backend models this facade has already built count as free for the planner.
+        """
+        edges = [(t.get_source_extension(), t.get_destination_extension())
+                 for t in self.discover_metamodel.get_transformations_m2m()]
+        model_hash = self.fm_model.canonical_hash()
+        return plan_backend(
+            operation_name,
+            source_extension=self.fm_model.get_extension(),
+            model_level=self._language_level(),
+            n_features=len(self.fm_model.get_features()),
+            plugins=self.discover_metamodel.plugins,
+            m2m_edges=edges,
+            artifact_available=lambda ext: artifact_cache.available_for(model_hash, ext),
+            available_models=set(self._backend_models),
+            allow_approximate=allow_approximate,
+        )
+
+    def plan(self, operation: str, *, allow_approximate: Optional[bool] = None) -> Plan:
+        """Which backend ``backend='auto'`` would run ``operation`` on this model, and why.
+
+        Returns the planner's :class:`~flamapy.core.planner.Plan` (plugin, target extension,
+        transformation chain, rationale, estimated cost in ms, alternatives) without running
+        anything. Raises :class:`~flamapy.core.exceptions.NoCompatibleBackendError` when no
+        installed plugin can run the operation on this model, and ``FlamaException`` when
+        ``operation`` is not a backend-selectable facade operation. ``allow_approximate``
+        falls back to the model's setting and the environment, like the operations do.
+        """
+        method = getattr(type(self), operation, None)
+        descriptor = getattr(method, '_facade_descriptor', None)
+        if descriptor is None or not descriptor.selectable_backend:
+            raise FlamaException(f"'{operation}' is not a backend-selectable facade operation.")
+        return self._plan_operation(operation, self._approximate_allowed(allow_approximate))
+
+    def _model_via_planner(self, descriptor: OperationDescriptor,
+                           allow_approximate: bool = False) -> VariabilityModel:
+        chosen = self._plan_operation(descriptor.name, allow_approximate)
+        self._last_planner = f'auto: {chosen.rationale}'
+        model = self.fm_model
+        for _, destination in chosen.transformation_chain:
+            if destination not in self._backend_models:
+                self._backend_models[destination] = (
+                    self.discover_metamodel.use_transformation_m2m(model, destination))
+            model = self._backend_models[destination]
+        return model
+
+    def _prepare_operation(
+        self, descriptor: OperationDescriptor, backend_arg: Optional[str],
+        call_kwargs: Dict[str, Any], allow_approximate: Optional[bool] = None,
+    ) -> tuple[Any, VariabilityModel]:
+        """Resolve the target model and a fully input-wired operation instance."""
+        model = self._model_for(descriptor, backend_arg, allow_approximate)
+        operation = self.discover_metamodel.get_operation(model, descriptor.operation)
+        if descriptor.input_adapter is not None:
+            descriptor.input_adapter(operation, self, call_kwargs)
+        else:
+            for input_spec in descriptor.inputs:
+                value = call_kwargs.get(input_spec.name)
+                if value is None:
+                    continue
+                if input_spec.kind == 'configuration':
+                    value = self._as_configuration(value)
+                if input_spec.setter is not None:
+                    getattr(operation, input_spec.setter)(value)
+        return operation, model
+
     def _run_operation(
         self, descriptor: OperationDescriptor, call_kwargs: Dict[str, Any]
     ) -> Any:
         """Resolve model + operation, wire inputs, execute, and marshal the result.
 
         Preserves the facade's historical contract: any :class:`FlamaException` is logged and the
-        call returns ``None``.
+        call returns ``None``, unless ``raise_errors`` (or ``FLAMAPY_RAISE_ERRORS=1``) asks for
+        the 3.0 contract, which raises it.
         """
+        self.last_result = None
         try:
             backend_arg = call_kwargs.pop('backend', None)
-            model = self._model_for(descriptor, backend_arg)
-            operation = self.discover_metamodel.get_operation(model, descriptor.operation)
-            if descriptor.input_adapter is not None:
-                descriptor.input_adapter(operation, self, call_kwargs)
-            else:
-                for input_spec in descriptor.inputs:
-                    value = call_kwargs.get(input_spec.name)
-                    if value is None:
-                        continue
-                    if input_spec.kind == 'configuration':
-                        value = self._as_configuration(value)
-                    if input_spec.setter is not None:
-                        getattr(operation, input_spec.setter)(value)
-            operation.execute(model)
-            result = operation.get_result()
+            allow_approximate = call_kwargs.pop('allow_approximate', None)
+            operation, model = self._prepare_operation(
+                descriptor, backend_arg, call_kwargs, allow_approximate)
+            # The hash is always the source feature model's (memoized there), whichever
+            # backend model the operation actually runs on.
+            envelope = run_and_wrap(
+                operation, model,
+                operation_name=descriptor.name, plugin=self._plugin_name_for(model),
+                model_hash=self.fm_model.canonical_hash())
             if descriptor.result_adapter is not None:
-                result = descriptor.result_adapter(result)
-            return result
+                envelope = dataclasses.replace(
+                    envelope, value=descriptor.result_adapter(envelope.value))
+            if self._last_planner is not None:
+                envelope = dataclasses.replace(envelope, planner=self._last_planner)
+            if getattr(model, '_flamapy_cache_hit', False):
+                envelope = dataclasses.replace(envelope, cache_hit=True)
+            self.last_result = envelope
+            return envelope.value
         except FlamaException as exception:
+            if _raise_errors(self.raise_errors):
+                raise
             logger.error("Error: %s", exception)
+            warnings.warn(
+                "Returning None on operation errors is deprecated: flamapy 3.0 will raise "
+                "the FlamaException instead. Catch FlamaException rather than checking for "
+                "None.", DeprecationWarning, stacklevel=3)
             return None
 
+    def _plugin_name_for(self, model: VariabilityModel) -> Optional[str]:
+        try:
+            return self.discover_metamodel.plugins.get_plugin_by_variability_model(model).name
+        except PluginNotFound:
+            return None
+
+    def run_async(self, operation: str, **kwargs: Any) -> Job:
+        """Run a facade operation asynchronously; returns a :class:`Job` immediately.
+
+        ``operation`` is the facade name (e.g. ``'configurations_number'``); ``kwargs``
+        are the same arguments the synchronous method takes (including ``backend=``).
+        ``job.result(timeout=...)`` waits for the value, raising ``OperationTimeout`` on
+        expiry (after requesting cooperative cancellation) — unlike the 2.x synchronous
+        methods, errors are **raised**, not swallowed into ``None``.
+
+        Everything after resolving the operation name runs inside the job — including the
+        fm->backend transformation (e.g. BDD compilation, often the expensive step on large
+        models) — so the timeout covers it and preparation errors (unknown backend,
+        invalid inputs) are raised by ``job.result()``.
+        """
+        method = getattr(type(self), operation, None)
+        descriptor = getattr(method, '_facade_descriptor', None)
+        if descriptor is None or getattr(method, '_facade_kind', None) != 'operation':
+            raise FlamaException(f"'{operation}' is not a facade analysis operation.")
+        call_kwargs = dict(kwargs)
+        backend_arg = call_kwargs.pop('backend', None)
+        allow_approximate = call_kwargs.pop('allow_approximate', None)
+
+        def task(interrupt_event: threading.Event) -> OperationResult[Any]:
+            prepared, model = self._prepare_operation(
+                descriptor, backend_arg, call_kwargs, allow_approximate)
+            if interrupt_event.is_set():
+                # The deadline expired (or cancel() was called) during preparation: the
+                # caller has already given up, so don't start the operation at all.
+                raise OperationTimeout(
+                    f"'{descriptor.name}' was cancelled before execution started.")
+            if isinstance(prepared, Interruptible):
+                prepared.set_interrupt_event(interrupt_event)
+            return run_and_wrap(
+                prepared, model,
+                operation_name=descriptor.name, plugin=self._plugin_name_for(model),
+                model_hash=self.fm_model.canonical_hash())
+
+        return default_engine().submit_call(task, result_adapter=descriptor.result_adapter)
+
+    def iter_configurations(self, backend: Optional[str] = None) -> Iterator[Configuration]:
+        """Iterate the valid configurations, yielding each as the solver produces it.
+
+        Unlike :meth:`configurations` (whose historical default is bdd), the backend
+        defaults to ``sat`` — the streaming-capable implementation. Non-streaming
+        backends fall back to full enumeration first. Same errors contract as
+        :meth:`run_async` (raises, never ``None``).
+        """
+        descriptor = type(self).configurations._facade_descriptor  # type: ignore[attr-defined]
+        operation, model = self._prepare_operation(descriptor, backend or 'sat', {})
+        if isinstance(operation, StreamingOperation):
+            return operation.iter_execute(model)
+        operation.execute(model)
+        return iter(operation.get_result())
+
 
 # One discovery instance, reused to install the operations and to run producers (which have no
 # per-facade instance to hold their own).
@@ -143,7 +379,9 @@ def _run_producer(descriptor: OperationDescriptor, call_kwargs: Dict[str, Any])
     """Run a 'producer' operation — one that *creates* a model instead of analysing one.
 
     Producers take no input model, so the operation is instantiated directly and executed with no
-    model. Same FlamaException -> None contract as :meth:`FLAMAFeatureModel._run_operation`.
+    model. Same FlamaException -> None contract as :meth:`FLAMAFeatureModel._run_operation`;
+    ``FLAMAPY_RAISE_ERRORS=1`` makes it raise instead (producers have no instance to carry
+    ``raise_errors``).
     """
     try:
         operation_class = next(
@@ -161,10 +399,21 @@ def _run_producer(descriptor: OperationDescriptor, call_kwargs: Dict[str, Any])
             result = descriptor.result_adapter(result)
         return result
     except FlamaException as exception:
+        if _raise_errors(None):
+            raise
         logger.error("Error: %s", exception)
+        warnings.warn(
+            "Returning None on operation errors is deprecated: flamapy 3.0 will raise "
+            "the FlamaException instead. Catch FlamaException rather than checking for "
+            "None.", DeprecationWarning, stacklevel=3)
         return None
 
 
+_SELECTABLE_NOTE = (
+    '\n\n``backend`` chooses the plugin that runs the operation (``"auto"`` lets the query '
+    'planner choose); ``allow_approximate`` only has an effect with ``backend="auto"``.')
+
+
 def _make_operation_method(descriptor: OperationDescriptor) -> Any:
     """Build a real callable from a descriptor.
 
@@ -184,6 +433,10 @@ def _make_operation_method(descriptor: OperationDescriptor) -> Any:
         parameters.append(inspect.Parameter(
             'backend', inspect.Parameter.POSITIONAL_OR_KEYWORD, default=None,
             annotation=Optional[str]))
+        # Only meaningful under backend='auto': let the planner pick approximate backends.
+        parameters.append(inspect.Parameter(
+            'allow_approximate', inspect.Parameter.KEYWORD_ONLY, default=None,
+            annotation=Optional[bool]))
     signature = inspect.Signature(parameters)
 
     def method(*args: Any, **kwargs: Any) -> Any:
@@ -197,7 +450,7 @@ def _make_operation_method(descriptor: OperationDescriptor) -> Any:
 
     method.__name__ = descriptor.name
     method.__qualname__ = f'{FLAMAFeatureModel.__name__}.{descriptor.name}'
-    method.__doc__ = descriptor.doc
+    method.__doc__ = descriptor.doc + (_SELECTABLE_NOTE if descriptor.selectable_backend else '')
     method.__signature__ = signature  # type: ignore[attr-defined]
     # Let the CLI/REST/tests tell analysis ops from producers/transformers without re-discovering.
     setattr(method, '_facade_kind', descriptor.kind)
@@ -211,4 +464,10 @@ def _install_operations(cls: type) -> None:
         setattr(cls, name, staticmethod(method) if descriptor.kind == 'producer' else method)
 
 
+# Async/streaming API methods, not descriptor-generated operations: the CLI generator and
+# the descriptor lock test filter on _facade_kind != 'operation'.
+FLAMAFeatureModel.plan._facade_kind = 'api'  # type: ignore[attr-defined]
+FLAMAFeatureModel.run_async._facade_kind = 'api'  # type: ignore[attr-defined]
+FLAMAFeatureModel.iter_configurations._facade_kind = 'api'  # type: ignore[attr-defined]
+
 _install_operations(FLAMAFeatureModel)

flamapy/interfaces/python/flamapy_feature_model.pyi

@@ -1,8 +1,10 @@
 # Auto-generated by flamapy.interfaces.python._stub — do not edit by hand.
 # Regenerate with: python -m flamapy.interfaces.python._stub
 from enum import Enum
-from typing import Any, Dict, List, Optional, Tuple, Union
+from typing import Any, Dict, List, Optional, Tuple, Union  # noqa: F401
 
+from flamapy.core.operations import OperationResult
+from flamapy.core.planner import Plan
 from flamapy.metamodels.configuration_metamodel.models import Configuration
 from flamapy.metamodels.fm_metamodel.models import FeatureModel
 
@@ -12,52 +14,71 @@ class Backend(str, Enum):
     BDD = ...
     Z3 = ...
     SHARPSAT = ...
+    SDD = ...
+    DNNF = ...
+    AUTO = ...
 
 
 class FLAMAFeatureModel:
     model_path: str
     fm_model: FeatureModel
     backend: Optional[Backend]
-    def __init__(self, model_path: str, backend: Optional[str] = ...) -> None: ...
-    def all_feature_bounds(self) -> Union[None, Dict[str, Dict[str, Any]]]: ...
-    def atomic_sets(self) -> Union[None, List[List[Any]]]: ...
-    def attribute_optimization(self, objectives: Any, backend: Optional[str] = ...) -> Union[None, List[Configuration]]: ...
-    def average_branching_factor(self) -> Union[None, float]: ...
-    def backbone(self) -> Union[None, Dict[str, List[Any]]]: ...
-    def commonality(self, configuration_path: str) -> Union[None, float]: ...
-    def configuration_conflict(self, configuration_path: str) -> Union[None, List[Any]]: ...
-    def configuration_repair(self, configuration_path: str) -> Union[None, List[Any]]: ...
-    def configurations(self, backend: Optional[str] = ...) -> Union[None, List[Configuration]]: ...
-    def configurations_number(self, backend: Optional[str] = ...) -> Union[None, int]: ...
-    def configurations_with_n_features(self, n: int) -> Union[None, List[Configuration]]: ...
-    def conflict(self, configuration_path: str, test_case_path: Optional[str] = ..., max_conflicts: Optional[int] = ...) -> Union[None, List[str]]: ...
-    def core_features(self, backend: Optional[str] = ...) -> Union[None, List[str]]: ...
-    def count_leafs(self) -> Union[None, int]: ...
-    def dead_features(self, backend: Optional[str] = ...) -> Union[None, List[str]]: ...
-    def diagnosis(self, configuration_path: str, test_case_path: Optional[str] = ..., max_diagnoses: Optional[int] = ...) -> Union[None, List[str]]: ...
-    def estimated_number_of_configurations(self) -> Union[None, int]: ...
-    def false_optional_features(self, backend: Optional[str] = ...) -> Union[None, List[str]]: ...
-    def feature_ancestors(self, feature_name: str) -> Union[None, List[str]]: ...
-    def feature_bounds(self, variable_name: str) -> Union[None, Dict[str, Any]]: ...
-    def feature_explanation(self, configuration_path: str, feature_name: str) -> Union[None, List[Any]]: ...
-    def feature_inclusion_probability(self) -> Union[None, Dict[str, float]]: ...
-    def filter(self, configuration_path: str) -> Union[None, List[Configuration]]: ...
+    allow_approximate: Optional[bool]
+    raise_errors: Optional[bool]
+    last_result: Optional[OperationResult[Any]]
+    def __init__(self, model_path: str, backend: Optional[str] = ...,
+                 *, allow_approximate: Optional[bool] = ...,
+                 raise_errors: Optional[bool] = ...) -> None: ...
+    def plan(self, operation: str, *, allow_approximate: Optional[bool] = ...) -> Plan: ...
+    def _plan_operation(self, operation_name: str, allow_approximate: bool = ...) -> Plan: ...
+    def run_async(self, operation: str, **kwargs: Any) -> Any: ...
+    def iter_configurations(self, backend: Optional[str] = ...) -> Any: ...
+    def all_feature_bounds(self) -> Optional[Dict[str, Dict[str, Any]]]: ...
+    def atomic_sets(self, backend: Optional[str] = ..., *, allow_approximate: Optional[bool] = ...) -> Optional[List[List[Any]]]: ...
+    def attribute_optimization(self, objectives: Any, backend: Optional[str] = ..., *, allow_approximate: Optional[bool] = ...) -> Optional[List[Configuration]]: ...
+    def average_branching_factor(self) -> Optional[float]: ...
+    def backbone(self) -> Optional[Dict[str, List[Any]]]: ...
+    def commonality(self, configuration_path: str, backend: Optional[str] = ..., *, allow_approximate: Optional[bool] = ...) -> Optional[float]: ...
+    def configuration_conflict(self, configuration_path: str) -> Optional[List[Any]]: ...
+    def configuration_repair(self, configuration_path: str) -> Optional[List[Any]]: ...
+    def configurations(self, backend: Optional[str] = ..., *, allow_approximate: Optional[bool] = ...) -> Optional[List[Configuration]]: ...
+    def configurations_number(self, backend: Optional[str] = ..., *, allow_approximate: Optional[bool] = ...) -> Optional[int]: ...
+    def configurations_with_n_features(self, n: int) -> Optional[List[Configuration]]: ...
+    def conflict(self, configuration_path: str, test_case_path: Optional[str] = ..., max_conflicts: Optional[int] = ...) -> Optional[List[str]]: ...
+    def core_features(self, backend: Optional[str] = ..., *, allow_approximate: Optional[bool] = ...) -> Optional[List[str]]: ...
+    def count_leafs(self) -> Optional[int]: ...
+    def coverage(self, configurations: Any, t: int = ...) -> Optional[float]: ...
+    def covering_array(self, t: int = ..., seed: Optional[int] = ...) -> Optional[List[Configuration]]: ...
+    def dead_features(self, backend: Optional[str] = ..., *, allow_approximate: Optional[bool] = ...) -> Optional[List[str]]: ...
+    def diagnosis(self, configuration_path: str, test_case_path: Optional[str] = ..., max_diagnoses: Optional[int] = ...) -> Optional[List[str]]: ...
+    def estimated_number_of_configurations(self) -> Optional[int]: ...
+    def explain_dead_feature(self, feature_name: str) -> Optional[List[str]]: ...
+    def explain_false_optional(self, feature_name: str) -> Optional[List[str]]: ...
+    def explain_void_model(self) -> Optional[List[str]]: ...
+    def false_optional_features(self, backend: Optional[str] = ..., *, allow_approximate: Optional[bool] = ...) -> Optional[List[str]]: ...
+    def feature_ancestors(self, feature_name: str) -> Optional[List[str]]: ...
+    def feature_bounds(self, variable_name: str) -> Optional[Dict[str, Any]]: ...
+    def feature_explanation(self, configuration_path: str, feature_name: str) -> Optional[List[Any]]: ...
+    def feature_inclusion_probability(self) -> Optional[Dict[str, float]]: ...
+    def filter(self, configuration_path: str) -> Optional[List[Configuration]]: ...
     def generate_random_attribute(self, name: str, min_value: int = ..., max_value: int = ..., only_leaf_features: bool = ...) -> FeatureModel: ...
     @staticmethod
     def generate_random_feature_model(num_features: int = ..., max_constraints: int = ..., seed: int = ..., void: bool = ..., language_level: str = ...) -> FeatureModel: ...
-    def homogeneity(self) -> Union[None, float]: ...
-    def language_level(self) -> Union[None, Any]: ...
-    def leaf_features(self) -> Union[None, List[str]]: ...
-    def max_depth(self) -> Union[None, int]: ...
-    def metrics(self) -> Union[None, List[Dict[str, Any]]]: ...
-    def minimum_configuration(self, backend: Optional[str] = ...) -> Union[None, Configuration]: ...
-    def product_distribution(self) -> Union[None, List[int]]: ...
-    def pure_optional_features(self) -> Union[None, List[str]]: ...
-    def sampling(self, size: int, with_replacement: bool = ..., backend: Optional[str] = ...) -> Union[None, List[Configuration]]: ...
-    def satisfiable(self, backend: Optional[str] = ...) -> Union[None, bool]: ...
-    def satisfiable_configuration(self, configuration_path: str, full_configuration: bool = ..., backend: Optional[str] = ...) -> Union[None, bool]: ...
-    def t_wise_sampling(self, t: int = ..., backend: Optional[str] = ...) -> Union[None, List[Configuration]]: ...
-    def unique_features(self) -> Union[None, List[str]]: ...
-    def variability(self) -> Union[None, Tuple[float, float]]: ...
-    def variant_features(self) -> Union[None, List[str]]: ...
-    def variation_points(self) -> Union[None, Dict[str, List[str]]]: ...
+    def homogeneity(self) -> Optional[float]: ...
+    def language_level(self) -> Optional[Any]: ...
+    def leaf_features(self) -> Optional[List[str]]: ...
+    def max_depth(self) -> Optional[int]: ...
+    def metrics(self) -> Optional[List[Dict[str, Any]]]: ...
+    def minimal_corrections(self, max_corrections: Optional[int] = ...) -> Optional[List[List[str]]]: ...
+    def minimum_configuration(self, backend: Optional[str] = ..., *, allow_approximate: Optional[bool] = ...) -> Optional[Configuration]: ...
+    def product_distribution(self) -> Optional[List[int]]: ...
+    def pure_optional_features(self) -> Optional[List[str]]: ...
+    def sample_reduction(self, configurations: Any, t: int = ...) -> Optional[List[Configuration]]: ...
+    def sampling(self, size: int, with_replacement: bool = ..., backend: Optional[str] = ..., *, allow_approximate: Optional[bool] = ...) -> Optional[List[Configuration]]: ...
+    def satisfiable(self, backend: Optional[str] = ..., *, allow_approximate: Optional[bool] = ...) -> Optional[bool]: ...
+    def satisfiable_configuration(self, configuration_path: str, full_configuration: bool = ..., backend: Optional[str] = ..., *, allow_approximate: Optional[bool] = ...) -> Optional[bool]: ...
+    def t_wise_sampling(self, t: int = ..., backend: Optional[str] = ..., *, allow_approximate: Optional[bool] = ...) -> Optional[List[Configuration]]: ...
+    def unique_features(self) -> Optional[List[str]]: ...
+    def variability(self) -> Optional[Tuple[float, float]]: ...
+    def variant_features(self) -> Optional[List[str]]: ...
+    def variation_points(self) -> Optional[Dict[str, List[str]]]: ...

{flamapy-2.6.0.dev12.dist-info → flamapy-2.9.0.dev0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: flamapy
-Version: 2.6.0.dev12
+Version: 2.9.0.dev0
 Summary: Flamapy feature model is a distribution of the flama framework containing all plugins required to analyze feature models. It also offers a richer API and a complete command line interface and documentation.
 Author-email: Flamapy <flamapy@us.es>
 License-Expression: GPL-3.0-or-later
@@ -8,11 +8,21 @@ Project-URL: Homepage, https://github.com/flamapy/flamapy-feature-model
 Requires-Python: >=3.11
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: flamapy-fw~=2.6.0.dev12
-Requires-Dist: flamapy-fm~=2.6.0.dev12
-Requires-Dist: flamapy-sat~=2.6.0.dev12
-Requires-Dist: flamapy-bdd~=2.6.0.dev12
-Requires-Dist: flamapy-z3~=2.6.0.dev12
+Requires-Dist: flamapy-fw~=2.9.0.dev0
+Requires-Dist: flamapy-fm~=2.9.0.dev0
+Requires-Dist: flamapy-sat~=2.9.0.dev0
+Requires-Dist: flamapy-bdd~=2.9.0.dev0
+Requires-Dist: flamapy-z3~=2.9.0.dev0
+Provides-Extra: sharpsat
+Requires-Dist: flamapy-sharpsat~=2.9.0.dev0; extra == "sharpsat"
+Provides-Extra: dnnf
+Requires-Dist: flamapy-dnnf~=2.9.0.dev0; extra == "dnnf"
+Provides-Extra: sdd
+Requires-Dist: flamapy-sdd~=2.9.0.dev0; extra == "sdd"
+Provides-Extra: all-solvers
+Requires-Dist: flamapy-sharpsat~=2.9.0.dev0; extra == "all-solvers"
+Requires-Dist: flamapy-dnnf~=2.9.0.dev0; extra == "all-solvers"
+Requires-Dist: flamapy-sdd~=2.9.0.dev0; extra == "all-solvers"
 Provides-Extra: dev
 Requires-Dist: pytest; extra == "dev"
 Requires-Dist: pytest-mock; extra == "dev"

flamapy-2.9.0.dev0.dist-info/RECORD

@@ -0,0 +1,11 @@
+flamapy/commands/__init__.py,sha256=DdRS2Xyt37H_k2YaaFWUcE6xfJALzllraerIup1l_OU,14646
+flamapy/interfaces/python/__init__.py,sha256=NVQH1l6O9ElD8YvUVBXJN0Y_ETmu3AbyQBZJJ9qiuoU,86
+flamapy/interfaces/python/_stub.py,sha256=7JMmnmxHFbpC7XHVqozZUooLwPbHS4p1-B8QXH5wQf8,3898
+flamapy/interfaces/python/flamapy_feature_model.py,sha256=Kfq-zizQViAx_KdfFZTo_SNkFakFo3FmNt32Z5Jaats,24180
+flamapy/interfaces/python/flamapy_feature_model.pyi,sha256=u-GtNc1wRslPO1I2sIIsNuOxrdT-dR0GZpqzyskHT34,6189
+flamapy-2.9.0.dev0.dist-info/licenses/LICENSE,sha256=46mU2C5kSwOnkqkw9XQAJlhBL2JAf1_uCD8lVcXyMRg,7652
+flamapy-2.9.0.dev0.dist-info/METADATA,sha256=lRl3wpwDCFvW98uPFWwZBzAYLmzQ2TCrh07g9yR7hso,1731
+flamapy-2.9.0.dev0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+flamapy-2.9.0.dev0.dist-info/entry_points.txt,sha256=CS_W4K9LW9xOf-7ymWD58KklNHBnhMHm0RXAZ9JLgVo,57
+flamapy-2.9.0.dev0.dist-info/top_level.txt,sha256=2YBI9dg4GVk28AJuyNu6dldi5Riwt5SP0zpNe2lSU5M,8
+flamapy-2.9.0.dev0.dist-info/RECORD,,

{flamapy-2.6.0.dev12.dist-info → flamapy-2.9.0.dev0.dist-info}/WHEEL

@@ -1,5 +1,5 @@
 Wheel-Version: 1.0
-Generator: setuptools (82.0.1)
+Generator: setuptools (84.2.1)
 Root-Is-Purelib: true
 Tag: py3-none-any
 

flamapy-2.6.0.dev12.dist-info/RECORD

@@ -1,11 +0,0 @@
-flamapy/commands/__init__.py,sha256=rajfqLxDAa5E4glNlLfUXQbIl5ZcgkGI6kTBKM9apSM,10144
-flamapy/interfaces/python/__init__.py,sha256=NVQH1l6O9ElD8YvUVBXJN0Y_ETmu3AbyQBZJJ9qiuoU,86
-flamapy/interfaces/python/_stub.py,sha256=SDlbrXrfQaJpgTzuScY-Q9IrkarGO96ad463NL0RJMY,2822
-flamapy/interfaces/python/flamapy_feature_model.py,sha256=sBZffI8CA4NA7Tzg9q7OaTCDKTV-EY-tWKQ8kdEEBkY,9840
-flamapy/interfaces/python/flamapy_feature_model.pyi,sha256=VdGtS3KdobqOEQfmvO_HTo2JkCNRB7UOWurKG4Xet64,4336
-flamapy-2.6.0.dev12.dist-info/licenses/LICENSE,sha256=46mU2C5kSwOnkqkw9XQAJlhBL2JAf1_uCD8lVcXyMRg,7652
-flamapy-2.6.0.dev12.dist-info/METADATA,sha256=-MRGwPu0iqotGx_mCjPPnuIOe5pw2CkOppIpX2lcPjU,1271
-flamapy-2.6.0.dev12.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
-flamapy-2.6.0.dev12.dist-info/entry_points.txt,sha256=CS_W4K9LW9xOf-7ymWD58KklNHBnhMHm0RXAZ9JLgVo,57
-flamapy-2.6.0.dev12.dist-info/top_level.txt,sha256=2YBI9dg4GVk28AJuyNu6dldi5Riwt5SP0zpNe2lSU5M,8
-flamapy-2.6.0.dev12.dist-info/RECORD,,