flamapy 2.6.0.dev12__tar.gz → 2.9.0.dev0__tar.gz

{flamapy-2.6.0.dev12 → flamapy-2.9.0.dev0}/PKG-INFO

@@ -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.6.0.dev12 → flamapy-2.9.0.dev0}/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-2.6.0.dev12 → flamapy-2.9.0.dev0}/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'