pyinfra 0.11.dev3__py3-none-any.whl → 3.5.1__py3-none-any.whl

pyinfra/api/operation.py

@@ -1,55 +1,210 @@
-'''
+"""
 Operations are the core of pyinfra. The ``@operation`` wrapper intercepts calls
 to the function and instead diff against the remote server, outputting commands
 to the deploy state. This is then run later by pyinfra's ``__main__`` or the
 :doc:`./pyinfra.api.operations` module.
-'''
+"""
+
+from __future__ import annotations
 
 from functools import wraps
-from inspect import getframeinfo, stack
-from os import path
+from inspect import signature
+from io import StringIO
 from types import FunctionType
+from typing import TYPE_CHECKING, Any, Callable, Generator, Iterator, Optional, cast
+
+from typing_extensions import ParamSpec, override
 
-from pyinfra import logger, pseudo_host, pseudo_state
-from pyinfra.pseudo_modules import PseudoModule
+import pyinfra
+from pyinfra import context, logger
+from pyinfra.context import ctx_host, ctx_state
 
-from .exceptions import PyinfraError
+from .arguments import EXECUTION_KWARG_KEYS, AllArguments, pop_global_arguments
+from .arguments_typed import PyinfraOperation
+from .command import PyinfraCommand, StringCommand
+from .exceptions import OperationValueError, PyinfraError
 from .host import Host
-from .state import State
+from .operations import run_host_op
+from .state import State, StateOperationHostData, StateOperationMeta, StateStage
 from .util import (
-    get_arg_value,
-    get_caller_frameinfo,
+    get_call_location,
+    get_file_sha1,
+    get_operation_order_from_stack,
+    log_operation_start,
     make_hash,
-    pop_op_kwargs,
-    unroll_generators,
 )
 
-
-# List of available operation names
-OPERATIONS = []
-
-
-def get_operation_names():
-    '''
-    Returns a list of available operations.
-    '''
-
-    return OPERATIONS
-
-
-class OperationMeta(object):
-    def __init__(self, hash=None, commands=None):
-        # Wrap all the attributes
-        commands = commands or []
-        self.commands = commands
-        self.hash = hash
-
-        # Changed flag = did we do anything?
-        self.changed = len(self.commands) > 0
+op_meta_default = object()
+
+if TYPE_CHECKING:
+    from pyinfra.connectors.util import CommandOutput
+
+
+class OperationMeta:
+    _hash: str
+
+    _combined_output: Optional["CommandOutput"] = None
+    _commands: Optional[list[Any]] = None
+    _maybe_is_change: Optional[bool] = None
+    _success: Optional[bool] = None
+    _retry_attempts: int = 0
+    _max_retries: int = 0
+    _retry_succeeded: Optional[bool] = None
+
+    def __init__(self, hash, is_change: Optional[bool]):
+        self._hash = hash
+        self._maybe_is_change = is_change
+
+    @override
+    def __repr__(self) -> str:
+        """
+        Return Operation object as a string.
+        """
+
+        if self._commands is not None:
+            retry_info = ""
+            if self._retry_attempts > 0:
+                retry_result = "succeeded" if self._retry_succeeded else "failed"
+                retry_info = (
+                    f", retries={self._retry_attempts}/{self._max_retries} ({retry_result})"
+                )
+
+            return (
+                "OperationMeta(executed=True, "
+                f"success={self.did_succeed()}, hash={self._hash}, "
+                f"commands={len(self._commands)}{retry_info})"
+            )
+        return (
+            f"OperationMeta(executed=False, maybeChange={self._maybe_is_change}, hash={self._hash})"
+        )
+
+    # Completion & status checks
+    def set_complete(
+        self,
+        success: bool,
+        commands: list[Any],
+        combined_output: "CommandOutput",
+        retry_attempts: int = 0,
+        max_retries: int = 0,
+    ) -> None:
+        if self.is_complete():
+            raise RuntimeError("Cannot complete an already complete operation")
+        self._success = success
+        self._commands = commands
+        self._combined_output = combined_output
+        self._retry_attempts = retry_attempts
+        self._max_retries = max_retries
+
+        # Determine if operation succeeded after retries
+        if retry_attempts > 0:
+            self._retry_succeeded = success
+
+    def is_complete(self) -> bool:
+        return self._success is not None
+
+    def _raise_if_not_complete(self) -> None:
+        if not self.is_complete():
+            raise RuntimeError("Cannot evaluate operation result before execution")
+
+    @property
+    def executed(self) -> bool:
+        if self._commands is None:
+            return False
+        return len(self._commands) > 0
+
+    @property
+    def will_change(self) -> bool:
+        if self._maybe_is_change is not None:
+            return self._maybe_is_change
+
+        op_data = context.state.get_op_data_for_host(context.host, self._hash)
+        cmd_gen = op_data.command_generator
+        for _ in cmd_gen():
+            self._maybe_is_change = True
+            return True
+        self._maybe_is_change = False
+        return False
+
+    def did_change(self) -> bool:
+        self._raise_if_not_complete()
+        return bool(self._success and len(self._commands or []) > 0)
+
+    def did_not_change(self) -> bool:
+        return not self.did_change()
+
+    def did_succeed(self, _raise_if_not_complete=True) -> bool:
+        if _raise_if_not_complete:
+            self._raise_if_not_complete()
+        return self._success is True
+
+    def did_error(self) -> bool:
+        self._raise_if_not_complete()
+        return self._success is False
+
+    # TODO: deprecated, remove in v4
+    @property
+    def changed(self) -> bool:
+        if self.is_complete():
+            return self.did_change()
+        return self.will_change
+
+    @property
+    def stdout_lines(self) -> list[str]:
+        self._raise_if_not_complete()
+        assert self._combined_output is not None
+        return self._combined_output.stdout_lines
+
+    @property
+    def stderr_lines(self) -> list[str]:
+        self._raise_if_not_complete()
+        assert self._combined_output is not None
+        return self._combined_output.stderr_lines
+
+    @property
+    def stdout(self) -> str:
+        return "\n".join(self.stdout_lines)
+
+    @property
+    def stderr(self) -> str:
+        return "\n".join(self.stderr_lines)
+
+    @property
+    def retry_attempts(self) -> int:
+        return self._retry_attempts
+
+    @property
+    def max_retries(self) -> int:
+        return self._max_retries
+
+    @property
+    def was_retried(self) -> bool:
+        """
+        Returns whether this operation was retried at least once.
+        """
+        return self._retry_attempts > 0
+
+    @property
+    def retry_succeeded(self) -> Optional[bool]:
+        """
+        Returns whether this operation succeeded after retries.
+        Returns None if the operation was not retried.
+        """
+        return self._retry_succeeded
+
+    def get_retry_info(self) -> dict[str, Any]:
+        """
+        Returns a dictionary with all retry-related information.
+        """
+        return {
+            "retry_attempts": self._retry_attempts,
+            "max_retries": self._max_retries,
+            "was_retried": self.was_retried,
+            "retry_succeeded": self._retry_succeeded,
+        }
 
 
-def add_op(state, op_func, *args, **kwargs):
-    '''
+def add_op(state: State, op_func, *args, **kwargs):
+    """
     Prepare & add an operation to ``pyinfra.state`` by executing it on all hosts.
 
     Args:
@@ -57,198 +212,96 @@ def add_op(state, op_func, *args, **kwargs):
         to op_func (function): the operation function from one of the modules,
         ie ``server.user``
         args/kwargs: passed to the operation function
-    '''
+    """
 
-    frameinfo = get_caller_frameinfo()
-    kwargs['frameinfo'] = frameinfo
+    if pyinfra.is_cli:
+        raise PyinfraError(
+            ("`add_op` should not be called when pyinfra is executing in CLI mode! ({0})").format(
+                get_call_location(),
+            ),
+        )
 
-    for host in state.inventory:
-        op_func(state, host, *args, **kwargs)
+    hosts = kwargs.pop("host", state.inventory.iter_active_hosts())
+    if isinstance(hosts, Host):
+        hosts = [hosts]
 
+    with ctx_state.use(state):
+        results = {}
+        for op_host in hosts:
+            with ctx_host.use(op_host):
+                results[op_host] = op_func(*args, **kwargs)
 
-def _get_call_location():
-    frames = stack()
+    return results
 
-    # Frist two frames are this and the caller below, so get the third item on
-    # the frame list, which should be the call to the actual operation.
-    frame = getframeinfo(frames[2][0])
 
-    return 'line {0} in {1}'.format(
-        frame.lineno,
-        path.relpath(frame.filename),
-    )
+P = ParamSpec("P")
 
 
-def operation(func=None, pipeline_facts=None):
-    '''
+def operation(
+    is_idempotent: bool = True,
+    idempotent_notice: Optional[str] = None,
+    is_deprecated: bool = False,
+    deprecated_for: Optional[str] = None,
+    _set_in_op: bool = True,
+) -> Callable[[Callable[P, Generator]], PyinfraOperation[P]]:
+    """
     Decorator that takes a simple module function and turn it into the internal
     operation representation that consists of a list of commands + options
     (sudo, (sudo|su)_user, env).
-    '''
+    """
 
-    # If not decorating, return function with config attached
-    if func is None:
-        def decorator(f):
-            setattr(f, 'pipeline_facts', pipeline_facts)
-            return operation(f)
+    def decorator(f: Callable[P, Generator]) -> PyinfraOperation[P]:
+        f.is_idempotent = is_idempotent  # type: ignore[attr-defined]
+        f.idempotent_notice = idempotent_notice  # type: ignore[attr-defined]
+        f.is_deprecated = is_deprecated  # type: ignore[attr-defined]
+        f.deprecated_for = deprecated_for  # type: ignore[attr-defined]
+        return _wrap_operation(f, _set_in_op=_set_in_op)
 
-        return decorator
+    return decorator
 
-    # Index the operation!
-    module_bits = func.__module__.split('.')
-    module_name = module_bits[-1]
-    op_name = '.'.join((module_name, func.__name__))
-    OPERATIONS.append(op_name)
 
-    # Actually decorate!
+def _wrap_operation(func: Callable[P, Generator], _set_in_op: bool = True) -> PyinfraOperation[P]:
     @wraps(func)
-    def decorated_func(*args, **kwargs):
-        # Prepare state/host
-        #
-
-        # If we're in CLI mode, there's no state/host passed down, we need to
-        # use the global "pseudo" modules.
-        if len(args) < 2 or not (
-            isinstance(args[0], (State, PseudoModule))
-            and isinstance(args[1], (Host, PseudoModule))
-        ):
-            state = pseudo_state._module
-            host = pseudo_host._module
-
-            if state.in_op:
-                raise PyinfraError((
-                    'Nested operation called without state/host: {0} ({1})'
-                ).format(op_name, _get_call_location()))
-
-            if state.in_deploy:
-                raise PyinfraError((
-                    'Nested deploy operation called without state/host: {0} ({1})'
-                ).format(op_name, _get_call_location()))
-
-        # Otherwise (API mode) we just trim off the commands
-        else:
-            args_copy = list(args)
-            state, host = args[0], args[1]
-            args = args_copy[2:]
-
-        # In API mode we have the kwarg - if a nested operation call we have
-        # current_frameinfo.
-        frameinfo = kwargs.pop('frameinfo', get_caller_frameinfo())
+    def decorated_func(*args: P.args, **kwargs: P.kwargs) -> OperationMeta:
+        state = context.state
+        host = context.host
+
+        if state.current_stage < StateStage.Prepare or state.current_stage > StateStage.Execute:
+            raise Exception("Cannot call operations outside of Prepare/Execute stages")
+
+        if host.in_op:
+            raise Exception(
+                "Operation called within another operation, this is not allowed! Use the `_inner` "
+                + "function to call the underlying operation."
+            )
+
+        if func.is_deprecated:  # type: ignore[attr-defined]
+            if func.deprecated_for:  # type: ignore[attr-defined]
+                logger.warning(
+                    f"The {get_operation_name_from_func(func)} operation is "
+                    + f"deprecated, please use: {func.deprecated_for}",  # type: ignore[attr-defined] # noqa
+                )
+            else:
+                logger.warning(f"The {get_operation_name_from_func(func)} operation is deprecated")
 
         # Configure operation
         #
-
-        # Name the operation
-        names = None
-        autoname = False
-
-        # Look for a set as the first argument
-        if len(args) > 0 and isinstance(args[0], set):
-            names = args[0]
-            args_copy = list(args)
-            args = args[1:]
-
-        # Generate an operation name if needed (Module/Operation format)
-        else:
-            autoname = True
-            module_bits = func.__module__.split('.')
-            module_name = module_bits[-1]
-            names = {
-                '{0}/{1}'.format(module_name.title(), func.__name__.title()),
-            }
-
-        if state.deploy_name:
-            names = {
-                '{0} | {1}'.format(state.deploy_name, name)
-                for name in names
-            }
-
         # Get the meta kwargs (globals that apply to all hosts)
-        op_meta_kwargs = pop_op_kwargs(state, kwargs)
-
-        # If this op is being called inside another, just return here
-        # (any unwanted/op-related kwargs removed above).
-        if state.in_op:
-            return func(state, host, *args, **kwargs) or []
-
-        line_number = frameinfo.lineno
-
-        # Inject the current op file number (only incremented in CLI mode)
-        op_lines = [state.current_op_file]
-
-        # Add any current @deploy line numbers
-        if state.deploy_line_numbers:
-            op_lines.extend(state.deploy_line_numbers)
-
-        # Add any current loop count
-        if state.loop_line:
-            op_lines.extend([state.loop_line, state.loop_counter])
-
-        # Add the line number that called this operation
-        op_lines.append(line_number)
-
-        # Make a hash from the call stack lines
-        op_hash = make_hash(op_lines)
-
-        # Avoid adding duplicates! This happens if an operation is called within
-        # a loop - such that the filename/lineno/code _are_ the same, but the
-        # arguments might be different. We just append an increasing number to
-        # the op hash and also handle below with the op order.
-        host_op_hashes = state.meta[host]['op_hashes']
-        duplicate_op_count = 0
-        while op_hash in host_op_hashes:
-            logger.debug('Duplicate hash ({0}) detected!'.format(op_hash))
-            op_hash = '{0}-{1}'.format(op_hash, duplicate_op_count)
-            duplicate_op_count += 1
-
-        host_op_hashes.add(op_hash)
-
-        if duplicate_op_count:
-            op_lines.append(duplicate_op_count)
-
-        op_lines = tuple(op_lines)
-        state.op_line_numbers_to_hash[op_lines] = op_hash
-        logger.debug('Adding operation, {0}, called @ {1}:{2}, opLines={3}, opHash={4}'.format(
-            names, frameinfo.filename, line_number, op_lines, op_hash,
-        ))
-
-        # Ensure shared (between servers) operation meta
-        op_meta = state.op_meta.setdefault(op_hash, {
-            'names': set(),
-            'args': [],
-        })
-
-        # Add any meta kwargs (sudo, etc) to the meta - first parse any strings
-        # as jinja templates.
-        actual_op_meta_kwargs = {
-            key: get_arg_value(state, host, a)
-            for key, a in op_meta_kwargs.items()
-        }
-        op_meta.update(actual_op_meta_kwargs)
-
-        # Add any new names to the set
-        op_meta['names'].update(names)
+        global_arguments, global_argument_keys = pop_global_arguments(state, host, kwargs)
 
-        # Attach normal args, if we're auto-naming this operation
-        if autoname:
-            for arg in args:
-                if isinstance(arg, FunctionType):
-                    arg = arg.__name__
+        names, add_args = generate_operation_name(func, host, kwargs, global_arguments)
+        op_order, op_hash = solve_operation_consistency(names, state, host)
 
-                if arg not in op_meta['args']:
-                    op_meta['args'].append(arg)
+        # Ensure shared (between servers) operation meta, mutates state
+        op_meta = ensure_shared_op_meta(state, op_hash, op_order, global_arguments, names)
 
-            # Attach keyword args
-            for key, value in kwargs.items():
-                arg = '='.join((str(key), str(value)))
-                if arg not in op_meta['args']:
-                    op_meta['args'].append(arg)
+        # Attach normal args, if we're auto-naming this operation
+        if add_args:
+            op_meta = attach_args(op_meta, args, kwargs)
 
         # Check if we're actually running the operation on this host
-        #
-
         # Run once and we've already added meta for this op? Stop here.
-        if op_meta_kwargs['run_once']:
+        if op_meta.global_arguments["_run_once"]:
             has_run = False
             for ops in state.ops.values():
                 if op_hash in ops:
@@ -256,71 +309,188 @@ def operation(func=None, pipeline_facts=None):
                     break
 
             if has_run:
-                return OperationMeta(op_hash)
-
-        # If we're limited, stop here - *after* we've created op_meta. This
-        # ensures the meta object always exists, even if no hosts actually ever
-        # execute the op (due to limit or otherwise).
-        hosts = op_meta_kwargs['hosts']
-        when = op_meta_kwargs['when']
-
-        if (
-            # Limited by the state's limit_hosts?
-            (state.limit_hosts is not None and host not in state.limit_hosts)
-            # Limited by the operation kwarg hosts?
-            or (hosts is not None and host not in hosts)
-            # Limited by the operation kwarg when? We check == because when is
-            # normally attribute wrapped as a AttrDataBool, which is actually
-            # an integer (Python doesn't allow subclassing bool!).
-            or when == False  # noqa
-        ):
-            return OperationMeta(op_hash)
-
-        # "Run" operation
-        #
+                return OperationMeta(op_hash, is_change=False)
+
+        # Grab a reference to any *current* deploy data as this may change when
+        # we later evaluate the operation at runtime.This means we put back the
+        # expected deploy data.
+        current_deploy_data = host.current_deploy_data
+
+        # "Run" operation - here we make a generator that will yield out actual commands to execute
+        # and, if we're diff-ing, we then iterate the generator now to determine if any changes
+        # *would* be made based on the *current* remote state.
+
+        def command_generator() -> Iterator[PyinfraCommand]:
+            # Check global _if argument function and do nothing if returns False
+            if state.is_executing:
+                _ifs = global_arguments.get("_if")
+                if isinstance(_ifs, list) and not all(_if() for _if in _ifs):
+                    return
+                elif callable(_ifs) and not _ifs():
+                    return
+
+            host.in_op = _set_in_op
+            host.current_op_hash = op_hash
+            host.current_op_global_arguments = global_arguments
+            host.current_op_deploy_data = current_deploy_data
+
+            try:
+                for command in func(*args, **kwargs):
+                    if isinstance(command, str):
+                        command = StringCommand(command.strip())
+                    yield command
+            finally:
+                host.in_op = False
+                host.current_op_hash = None
+                host.current_op_global_arguments = None
+                host.current_op_deploy_data = None
+
+        op_is_change = None
+        if state.should_check_for_changes():
+            op_is_change = False
+            for _ in command_generator():
+                op_is_change = True
+                break
+        else:
+            # If not calling the op function to check for change we still want to ensure the args
+            # are valid, so use Signature.bind to trigger any TypeError.
+            signature(func).bind(*args, **kwargs)
+
+        # Add host-specific operation data to state, this mutates state
+        host_meta = state.get_meta_for_host(host)
+        host_meta.ops += 1
+        if op_is_change:
+            host_meta.ops_change += 1
+        else:
+            host_meta.ops_no_change += 1
 
-        # Otherwise, flag as in-op and run it to get the commands
-        state.in_op = True
-        state.current_op_hash = op_hash
-
-        # Generate actual arguments by parsing strings as jinja2 templates. This
-        # means you can string format arguments w/o generating multiple
-        # operations. Only affects top level operations, as must be run "in_op"
-        # so facts are gathered correctly.
-        actual_args = [
-            get_arg_value(state, host, a)
-            for a in args
-        ]
-
-        actual_kwargs = {
-            key: get_arg_value(state, host, a)
-            for key, a in kwargs.items()
-        }
+        operation_meta = OperationMeta(op_hash, op_is_change)
 
-        # Convert to list as the result may be a generator
-        commands = unroll_generators(func(
-            state, host,
-            *actual_args,
-            **actual_kwargs
-        ))
+        # Add the server-relevant commands
+        op_data = StateOperationHostData(command_generator, global_arguments, operation_meta)
+        state.set_op_data_for_host(host, op_hash, op_data)
 
-        state.in_op = False
-        state.current_op_hash = None
+        # If we're already in the execution phase, execute this operation immediately
+        if state.is_executing:
+            execute_immediately(state, host, op_hash)
 
-        # Add host-specific operation data to state
-        #
+        # Return result meta for use in deploy scripts
+        return operation_meta
+
+    decorated_func._inner = func  # type: ignore[attr-defined]
+    return cast(PyinfraOperation[P], decorated_func)
 
-        # We're doing some commands, meta/ops++
-        state.meta[host]['ops'] += 1
-        state.meta[host]['commands'] += len(commands)
 
-        # Add the server-relevant commands
-        state.ops[host][op_hash] = {
-            'commands': commands,
-        }
+def get_operation_name_from_func(func):
+    if func.__module__:
+        module_bits = func.__module__.split(".")
+        module_name = module_bits[-1]
+        return "{0}.{1}".format(module_name, func.__name__)
+    else:
+        return func.__name__
+
+
+def generate_operation_name(func, host, kwargs, global_arguments):
+    # Generate an operation name if needed (Module/Operation format)
+    name = global_arguments.get("name")
+    add_args = False
+    if name:
+        names = {name}
+    else:
+        add_args = True
+        name = get_operation_name_from_func(func)
+        names = {name}
+
+    if host.current_deploy_name:
+        names = {"{0} | {1}".format(host.current_deploy_name, name) for name in names}
+
+    return names, add_args
+
+
+def solve_operation_consistency(names, state, host):
+    # Operation order is used to tie-break available nodes in the operation DAG, in CLI mode
+    # we use stack call order so this matches as defined by the user deploy code.
+    if pyinfra.is_cli:
+        op_order = get_operation_order_from_stack(state)
+    # In API mode we just increase the order for each host
+    else:
+        op_order = [len(host.op_hash_order)]
+
+    if host.loop_position:
+        op_order.extend(host.loop_position)
+
+    # Make a hash from the call stack lines
+    op_hash = make_hash(op_order)
+
+    # Avoid adding duplicates! This happens if an operation is called within
+    # a loop - such that the filename/lineno/code _are_ the same, but the
+    # arguments might be different. We just append an increasing number to
+    # the op hash and also handle below with the op order.
+    duplicate_op_count = 0
+    while op_hash in host.op_hash_order:
+        logger.debug("Duplicate hash ({0}) detected!".format(op_hash))
+        op_hash = "{0}-{1}".format(op_hash, duplicate_op_count)
+        duplicate_op_count += 1
+
+    host.op_hash_order.append(op_hash)
+    if duplicate_op_count:
+        op_order.append(duplicate_op_count)
+
+    op_order = tuple(op_order)
+    logger.debug(f"Adding operation, {names}, opOrder={op_order}, opHash={op_hash}")
+    return op_order, op_hash
+
+
+# NOTE: this function mutates state.op_meta for this hash
+def ensure_shared_op_meta(
+    state: State,
+    op_hash: str,
+    op_order: tuple[int, ...],
+    global_arguments: AllArguments,
+    names: set[str],
+):
+    op_meta = state.op_meta.setdefault(op_hash, StateOperationMeta(op_order))
+
+    for key in EXECUTION_KWARG_KEYS:
+        global_value = global_arguments.pop(key)  # type: ignore[misc]
+        op_meta_value = op_meta.global_arguments.get(key, op_meta_default)
+
+        if op_meta_value is not op_meta_default and global_value != op_meta_value:
+            raise OperationValueError("Cannot have different values for `{0}`.".format(key))
+
+        op_meta.global_arguments[key] = global_value  # type: ignore[literal-required]
+
+    # Add any new names to the set
+    op_meta.names.update(names)
+
+    return op_meta
+
+
+def execute_immediately(state, host, op_hash):
+    op_meta = state.get_op_meta(op_hash)
+    op_data = state.get_op_data_for_host(host, op_hash)
+    op_data.parent_op_hash = host.executing_op_hash
+    log_operation_start(op_meta, op_types=["nested"], prefix="")
+    run_host_op(state, host, op_hash)
 
-        # Return result meta for use in deploy scripts
-        return OperationMeta(op_hash, commands)
 
-    decorated_func._pyinfra_op = func
-    return decorated_func
+def _get_arg_value(arg):
+    if isinstance(arg, FunctionType):
+        return arg.__name__
+    if isinstance(arg, StringIO):
+        return f"StringIO(hash={get_file_sha1(arg)})"
+    return arg
+
+
+def attach_args(op_meta, args, kwargs):
+    for arg in args:
+        if arg not in op_meta.args:
+            op_meta.args.append(str(_get_arg_value(arg)))
+
+    # Attach keyword args
+    for key, value in kwargs.items():
+        arg = "=".join((str(key), str(_get_arg_value(value))))
+        if arg not in op_meta.args:
+            op_meta.args.append(arg)
+
+    return op_meta