ob-metaflow-stubs 6.0.4.7__py2.py3-none-any.whl → 6.0.4.8rc1__py2.py3-none-any.whl

metaflow-stubs/user_decorators/mutable_step.pyi

@@ -0,0 +1,152 @@
+######################################################################################################
+#                                 Auto-generated Metaflow stub file                                  #
+# MF version: 2.16.5.1+obcheckpoint(0.2.4);ob(v1)                                                    #
+# Generated on 2025-07-28T18:04:46.419621                                                            #
+######################################################################################################
+
+from __future__ import annotations
+
+import typing
+if typing.TYPE_CHECKING:
+    import functools
+    import typing
+    import metaflow.flowspec
+    import metaflow.user_decorators.user_step_decorator
+    import metaflow.decorators
+    import metaflow.user_decorator.mutable_flow
+
+from ..exception import MetaflowException as MetaflowException
+from .user_step_decorator import StepMutator as StepMutator
+from .user_step_decorator import UserStepDecoratorBase as UserStepDecoratorBase
+
+TYPE_CHECKING: bool
+
+class MutableStep(object, metaclass=type):
+    def __init__(self, flow_spec: "metaflow.flowspec.FlowSpec", step: typing.Union[typing.Callable[["metaflow.decorators.FlowSpecDerived"], None], typing.Callable[["metaflow.decorators.FlowSpecDerived", typing.Any], None]], pre_mutate: bool = False, statically_defined: bool = False, inserted_by: typing.Optional[str] = None):
+        ...
+    @property
+    def flow(self) -> "metaflow.user_decorator.mutable_flow.MutableFlow":
+        """
+        The flow that contains this step
+        
+        Returns
+        -------
+        MutableFlow
+            The flow that contains this step
+        """
+        ...
+    @property
+    def decorator_specs(self) -> typing.Generator[typing.Tuple[str, str, typing.List[typing.Any], typing.Dict[str, typing.Any]], None, None]:
+        """
+        Iterate over all the decorator specifications of this step. Note that the same
+        type of decorator may be present multiple times and no order is guaranteed.
+        
+        The returned tuple contains:
+        - The decorator's name (shortest possible)
+        - The decorator's fully qualified name (in the case of Metaflow decorators, this
+          will indicate which extension the decorator comes from)
+        - A list of positional arguments
+        - A dictionary of keyword arguments
+        
+        You can use the resulting tuple to remove a decorator for example
+        
+        Yields
+        ------
+        str, str, List[Any], Dict[str, Any]
+            A tuple containing the decorator name, it's fully qualified name,
+            a list of positional arguments, and a dictionary of keyword arguments.
+        """
+        ...
+    def add_decorator(self, deco_type: typing.Union[functools.partial, metaflow.user_decorators.user_step_decorator.UserStepDecoratorBase, str], deco_args: typing.Optional[typing.List[typing.Any]] = None, deco_kwargs: typing.Optional[typing.Dict[str, typing.Any]] = None, duplicates: int = 1):
+        """
+        Add a Metaflow step-decorator or a user step-decorator to a step.
+        
+        You can either add the decorator itself or its decorator specification for it
+        (the same you would get back from decorator_specs). You can also mix and match
+        but you cannot provide arguments both through the string and the
+        deco_args/deco_kwargs.
+        
+        As an example:
+        ```
+        from metaflow import environment
+        ...
+        my_step.add_decorator(environment, deco_kwargs={"vars": {"foo": 42})}
+        ```
+        
+        is equivalent to:
+        ```
+        my_step.add_decorator('environment:vars={"foo": 42}')
+        ```
+        
+        is equivalent to:
+        ```
+        my_step.add_decorator('environment', deco_kwargs={"vars":{"foo": 42}})
+        ```
+        
+        but this is not allowed:
+        ```
+        my_step.add_decorator('environment:vars={"bar" 43}', deco_kwargs={"vars":{"foo": 42}})
+        ```
+        
+        Note in the case where you specify a
+        string for the decorator, there is no need to import the decorator.
+        
+        The string syntax is useful to, for example, allow decorators to be stored as
+        strings in a configuration file.
+        
+        You can only add StepMutators in the pre_mutate stage.
+        
+        In terms of precedence for decorators:
+          - if a decorator can be applied multiple times (like `@card`) all decorators
+            added are kept.
+          - if `duplicates` is set to `MutableStep.IGNORE`, then the decorator
+            being added is ignored (in other words, the existing decorator has precedence).
+          - if `duplicates` is set to `MutableStep.OVERRIDE`, then the *existing*
+            decorator is removed and this newly added one replaces it (in other
+            words, the newly added decorator has precedence).
+          - if `duplicates` is set to `MutableStep.ERROR`, then an error is raised but only
+            if the newly added decorator is *static* (ie: defined directly in the code).
+            If not, it is ignored.
+        
+        Parameters
+        ----------
+        deco_type : Union[partial, UserStepDecoratorBase, str]
+            The decorator class to add to this step.
+        deco_args : List[Any], optional, default None
+            Positional arguments to pass to the decorator.
+        deco_kwargs : Dict[str, Any], optional, default None
+            Keyword arguments to pass to the decorator.
+        duplicates : int, default MutableStep.IGNORE
+            Instruction on how to handle duplicates. It can be one of:
+            - `MutableStep.IGNORE`: Ignore the decorator if it already exists.
+            - `MutableStep.ERROR`: Raise an error if the decorator already exists.
+            - `MutableStep.OVERRIDE`: Remove the existing decorator and add this one.
+        """
+        ...
+    def remove_decorator(self, deco_name: str, deco_args: typing.Optional[typing.List[typing.Any]] = None, deco_kwargs: typing.Optional[typing.Dict[str, typing.Any]] = None) -> bool:
+        """
+        Remove a step-level decorator. To remove a decorator, you can pass the decorator
+        specification (obtained from `decorator_specs` for example).
+        Note that if multiple decorators share the same decorator specification
+        (very rare), they will all be removed.
+        
+        You can only remove StepMutators in the `pre_mutate` method.
+        
+        Parameters
+        ----------
+        deco_name : str
+            Decorator specification of the decorator to remove. If nothing else is
+            specified, all decorators matching that name will be removed.
+        deco_args : List[Any], optional, default None
+            Positional arguments to match the decorator specification.
+        deco_kwargs : Dict[str, Any], optional, default None
+            Keyword arguments to match the decorator specification.
+        
+        Returns
+        -------
+        bool
+            Returns True if a decorator was removed.
+        """
+        ...
+    ...
+

metaflow-stubs/user_decorators/user_flow_decorator.pyi

@@ -0,0 +1,137 @@
+######################################################################################################
+#                                 Auto-generated Metaflow stub file                                  #
+# MF version: 2.16.5.1+obcheckpoint(0.2.4);ob(v1)                                                    #
+# Generated on 2025-07-28T18:04:46.391409                                                            #
+######################################################################################################
+
+from __future__ import annotations
+
+import metaflow
+import typing
+if typing.TYPE_CHECKING:
+    import metaflow.flowspec
+    import metaflow.user_decorators.mutable_flow
+    import metaflow.user_decorators.user_flow_decorator
+    import metaflow.decorators
+
+from ..exception import MetaflowException as MetaflowException
+from ..user_configs.config_parameters import resolve_delayed_evaluator as resolve_delayed_evaluator
+from ..user_configs.config_parameters import unpack_delayed_evaluator as unpack_delayed_evaluator
+from .common import ClassPath_Trie as ClassPath_Trie
+
+TYPE_CHECKING: bool
+
+class FlowMutatorMeta(type, metaclass=type):
+    @staticmethod
+    def __new__(mcs, name, bases, namespace):
+        ...
+    @classmethod
+    def all_decorators(mcs) -> typing.Dict[str, "FlowMutatorMeta"]:
+        ...
+    def __str__(cls):
+        ...
+    @classmethod
+    def get_decorator_by_name(mcs, decorator_name: str) -> typing.Union["FlowDecoratorMeta", "metaflow.decorators.Decorator", None]:
+        """
+        Get a decorator by its name.
+        
+        Parameters
+        ----------
+        decorator_name: str
+            The name of the decorator to retrieve.
+        
+        Returns
+        -------
+        Optional[FlowDecoratorMeta]
+            The decorator class if found, None otherwise.
+        """
+        ...
+    @classmethod
+    def get_decorator_name(mcs, decorator_type: type) -> typing.Optional[str]:
+        """
+        Get the minimally unique classpath name for a decorator type.
+        
+        Parameters
+        ----------
+        decorator_type: type
+            The type of the decorator to retrieve the name for.
+        
+        Returns
+        -------
+        Optional[str]
+            The minimally unique classpath name if found, None otherwise.
+        """
+        ...
+    ...
+
+class FlowMutator(object, metaclass=FlowMutatorMeta):
+    """
+    Derive from this class to implement a flow mutator.
+    
+    A flow mutator allows you to introspect a flow and its included steps. You can
+    then add parameters, configurations and decorators to the flow as well as modify
+    any of its steps.
+    use values available through configurations to determine how to mutate the flow.
+    
+    There are two main methods provided:
+      - pre_mutate: called as early as possible right after configuration values are read.
+      - mutate: called right after all the command line is parsed but before any
+        Metaflow decorators are applied.
+    
+    The `mutate` method does not allow you to modify the flow itself but you can still
+    modify the steps.
+    """
+    def __init__(self, *args, **kwargs):
+        ...
+    def __mro_entries__(self, bases):
+        ...
+    def __call__(self, flow_spec: typing.Optional["metaflow.flowspec.FlowSpecMeta"] = None) -> "metaflow.flowspec.FlowSpecMeta":
+        ...
+    def __str__(self):
+        ...
+    def init(self, *args, **kwargs):
+        """
+        Implement this method if you wish for your FlowMutator to take in arguments.
+        
+        Your flow-mutator can then look like:
+        
+        @MyMutator(arg1, arg2)
+        class MyFlow(FlowSpec):
+            pass
+        
+        It is an error to use your mutator with arguments but not implement this method.
+        """
+        ...
+    def external_init(self):
+        ...
+    def pre_mutate(self, mutable_flow: "metaflow.user_decorators.mutable_flow.MutableFlow"):
+        """
+        Method called right after all configuration values are read.
+        
+        Parameters
+        ----------
+        mutable_flow : metaflow.user_decorators.mutable_flow.MutableFlow
+            A representation of this flow
+        """
+        ...
+    def mutate(self, mutable_flow: "metaflow.user_decorators.mutable_flow.MutableFlow"):
+        """
+        Method called right before the first Metaflow step decorator is applied. This
+        means that the command line, including all `--with` options has been parsed.
+        
+        Given how late this function is called, there are a few restrictions on what
+        you can do; the following methods on MutableFlow are not allowed and calling
+        them will result in an error:
+          - add_parameter/remove_parameter
+          - add_decorator/remove_decorator
+        
+        To call these methods, use the `pre_mutate` method instead.
+        
+        Parameters
+        ----------
+        mutable_flow : metaflow.user_decorators.mutable_flow.MutableFlow
+            A representation of this flow
+        """
+        ...
+    ...
+

metaflow-stubs/user_decorators/user_step_decorator.pyi

@@ -0,0 +1,323 @@
+######################################################################################################
+#                                 Auto-generated Metaflow stub file                                  #
+# MF version: 2.16.5.1+obcheckpoint(0.2.4);ob(v1)                                                    #
+# Generated on 2025-07-28T18:04:46.390684                                                            #
+######################################################################################################
+
+from __future__ import annotations
+
+import metaflow
+import typing
+if typing.TYPE_CHECKING:
+    import metaflow.datastore.inputs
+    import metaflow.user_decorators.mutable_step
+    import typing
+    import metaflow.flowspec
+    import metaflow.user_decorators.user_step_decorator
+    import metaflow.decorators
+
+from ..exception import MetaflowException as MetaflowException
+from ..user_configs.config_parameters import resolve_delayed_evaluator as resolve_delayed_evaluator
+from ..user_configs.config_parameters import unpack_delayed_evaluator as unpack_delayed_evaluator
+from .common import ClassPath_Trie as ClassPath_Trie
+
+TYPE_CHECKING: bool
+
+USER_SKIP_STEP: dict
+
+class UserStepDecoratorMeta(type, metaclass=type):
+    @staticmethod
+    def __new__(mcs, name, bases, namespace, **_kwargs):
+        ...
+    def __str__(cls):
+        ...
+    @classmethod
+    def all_decorators(mcs) -> typing.Dict[str, "UserStepDecoratorMeta"]:
+        """
+        Get all registered decorators using the minimally unique classpath name
+        
+        Returns
+        -------
+        Dict[str, UserStepDecoratorBase]
+            A dictionary mapping decorator names to their classes.
+        """
+        ...
+    @classmethod
+    def get_decorator_by_name(mcs, decorator_name: str) -> typing.Union["UserStepDecoratorBase", "metaflow.decorators.Decorator", None]:
+        """
+        Get a decorator by its name.
+        
+        Parameters
+        ----------
+        decorator_name: str
+            The name of the decorator to retrieve.
+        
+        Returns
+        -------
+        Optional[UserStepDecoratorBase]
+            The decorator class if found, None otherwise.
+        """
+        ...
+    @classmethod
+    def get_decorator_name(mcs, decorator_type: type) -> typing.Optional[str]:
+        """
+        Get the minimally unique classpath name for a decorator type.
+        
+        Parameters
+        ----------
+        decorator_type: type
+            The type of the decorator to retrieve the name for.
+        
+        Returns
+        -------
+        Optional[str]
+            The minimally unique classpath name if found, None otherwise.
+        """
+        ...
+    ...
+
+class UserStepDecoratorBase(object, metaclass=UserStepDecoratorMeta):
+    def __init__(self, *args, **kwargs):
+        ...
+    def __get__(self, instance, owner):
+        ...
+    def __call__(self, step: typing.Union[typing.Callable[["metaflow.decorators.FlowSpecDerived"], None], typing.Callable[["metaflow.decorators.FlowSpecDerived", typing.Any], None], None] = None, **kwargs) -> typing.Union[typing.Callable[["metaflow.decorators.FlowSpecDerived"], None], typing.Callable[["metaflow.decorators.FlowSpecDerived", typing.Any], None]]:
+        ...
+    def add_or_raise(self, step: typing.Union[typing.Callable[["metaflow.decorators.FlowSpecDerived"], None], typing.Callable[["metaflow.decorators.FlowSpecDerived", typing.Any], None]], statically_defined: bool, duplicates: int, inserted_by: typing.Optional[str] = None):
+        ...
+    def __str__(self):
+        ...
+    @classmethod
+    def extract_args_kwargs_from_decorator_spec(cls, deco_spec: str) -> typing.Tuple[typing.List[typing.Any], typing.Dict[str, typing.Any]]:
+        ...
+    @classmethod
+    def parse_decorator_spec(cls, deco_spec: str) -> typing.Optional["UserStepDecoratorBase"]:
+        ...
+    def make_decorator_spec(self):
+        ...
+    def get_args_kwargs(self) -> typing.Tuple[typing.List[typing.Any], typing.Dict[str, typing.Any]]:
+        """
+        Get the arguments and keyword arguments of the decorator.
+        
+        Returns
+        -------
+        Tuple[List[Any], Dict[str, Any]]
+            A tuple containing a list of arguments and a dictionary of keyword arguments.
+        """
+        ...
+    def init(self, *args, **kwargs):
+        ...
+    def external_init(self):
+        ...
+    @classmethod
+    def __init_subclass__(cls_, **_kwargs):
+        ...
+    ...
+
+class UserStepDecorator(UserStepDecoratorBase, metaclass=UserStepDecoratorMeta):
+    def init(self, *args, **kwargs):
+        """
+        Implement this method if your UserStepDecorator takes arguments. It replaces the
+        __init__ method in traditional Python classes.
+        
+        
+        As an example:
+        ```
+        class MyDecorator(UserStepDecorator):
+            def init(self, *args, **kwargs):
+                self.arg1 = kwargs.get("arg1", None)
+                self.arg2 = kwargs.get("arg2", None)
+                # Do something with the arguments
+        ```
+        
+        can then be used as
+        ```
+        @MyDecorator(arg1=42, arg2=conf_expr("config.my_arg2"))
+        @step
+        def start(self):
+            pass
+        ```
+        """
+        ...
+    def pre_step(self, step_name: str, flow: "metaflow.flowspec.FlowSpec", inputs: typing.Optional["metaflow.datastore.inputs.Inputs"] = None) -> typing.Optional[typing.Callable[["metaflow.flowspec.FlowSpec", typing.Optional[typing.Any]], typing.Any]]:
+        """
+        Implement this method to perform any action prior to the execution of a step.
+        
+        It should return either None to execute anything wrapped by this step decorator
+        as usual or a callable that will be called instead.
+        
+        Parameters
+        ----------
+        step_name: str
+            The name of the step being decorated.
+        flow: FlowSpec
+            The flow object to which the step belongs.
+        inputs: Optional[List[FlowSpec]]
+            The inputs to the step being decorated. This is only provided for join steps
+            and is None for all other steps.
+        
+        Returns
+        -------
+        Optional[Callable[FlowSpec, Optional[Any]]]
+            An optional function to use instead of the wrapped step. Note that the function
+            returned should match the signature of the step being wrapped (join steps
+            take an additional "inputs" argument).
+        """
+        ...
+    def post_step(self, step_name: str, flow: "metaflow.flowspec.FlowSpec", exception: typing.Optional[Exception] = None):
+        """
+        Implement this method to perform any action after the execution of a step.
+        
+        If the step (or any code being wrapped by this decorator) raises an exception,
+        it will be passed here and can either be caught (in which case the step will
+        be considered as successful) or re-raised (in which case the entire step
+        will be considered a failure unless another decorator catches the execption).
+        
+        Note that this method executes *before* artifacts are stored in the datastore
+        so it is able to modify, add or remove artifacts from `flow`.
+        
+        Parameters
+        ----------
+        step_name: str
+            The name of the step being decorated.
+        flow: FlowSpec
+            The flow object to which the step belongs.
+        exception: Optional[Exception]
+            The exception raised during the step execution, if any.
+        """
+        ...
+    @property
+    def skip_step(self) -> typing.Union[bool, typing.Dict[str, typing.Any]]:
+        """
+        Returns whether or not the step (or rather anything wrapped by this decorator)
+        should be skipped
+        
+        Returns
+        -------
+        Union[bool, Dict[str, Any]]
+            False if the step should not be skipped. True if it should be skipped and
+            a dictionary if it should be skipped and the values passed in used as
+            the arguments to the self.next call.
+        """
+        ...
+    @skip_step.setter
+    def skip_step(self, value: typing.Union[bool, typing.Dict[str, typing.Any]]):
+        """
+        Set the skip_step property. You can set it to:
+          - True to skip the step
+          - False to not skip the step (default)
+          - A dictionary with the keys valid in the `self.next` call.
+        
+        Parameters
+        ----------
+        value: Union[bool, Dict[str, Any]]
+            True/False or a dictionary with the keys valid in the `self.next` call.
+        """
+        ...
+    ...
+
+def user_step_decorator(*args, **kwargs):
+    """
+    Use this decorator to transform a generator function into a user step decorator.
+    
+    As an example:
+    
+    ```
+    @user_step_decorator
+    def timing(step_name, flow, inputs):
+        start_time = time.time()
+        yield
+        end_time = time.time()
+        flow.artifact_total_time = end_time - start_time
+        print(f"Step {step_name} took {flow.artifact_total_time} seconds")
+    ```
+    which can then be used as:
+    
+    ```
+    @timing
+    @step
+    def start(self):
+        print("Hello, world!")
+    ```
+    
+    Your generator should:
+      - yield at most once -- if you do not yield, the step will not execute.
+      - yield:
+          - None
+          - a callable that will replace whatever is being wrapped (it
+            should have the same parameters as the wrapped function, namely, it should
+            be a
+            Callable[[FlowSpec, Inputs], Optional[Union[Dict[str, Any]]]]).
+            Note that the return type is a bit different -- you can return:
+              - None: no special behavior;
+              - A dictionary containing parameters for `self.next()`.
+          - a dictionary to skip the step. An empty dictionary is equivalent
+            to just skipping the step. A full dictionary will pass the arguments
+            to the `self.next()` call -- this allows you to modify the behavior
+            of `self.next` (for example, changing the `foreach` values. We provide
+            USER_SKIP_STEP as a special value that is equivalent to {}.
+    
+    
+    You are able to catch exceptions thrown by the yield statement (ie: coming from the
+    wrapped code). Catching and not re-raising the exception will make the step
+    successful.
+    
+    Note that you are able to modify the step's artifact after the yield.
+    
+    For more complex use cases, you can use the `UserStepDecorator` class directly which
+    allows more control.
+    """
+    ...
+
+class StepMutator(UserStepDecoratorBase, metaclass=UserStepDecoratorMeta):
+    """
+    Derive from this class to implement a step mutator.
+    
+    A step mutator allows you to introspect a step and add decorators to it. You can
+    use values available through configurations to determine how to mutate the step.
+    
+    There are two main methods provided:
+      - pre_mutate: called as early as possible right after configuration values are read.
+      - mutate: called right after all the command line is parsed but before any
+        Metaflow decorators are applied.
+    """
+    def init(self, *args, **kwargs):
+        """
+        Implement this method if you wish for your StepMutator to take in arguments.
+        
+        Your step-mutator can then look like:
+        
+        @MyMutator(arg1, arg2)
+        @step
+        def my_step(self):
+            pass
+        
+        It is an error to use your mutator with arguments but not implement this method.
+        """
+        ...
+    def pre_mutate(self, mutable_step: "metaflow.user_decorators.mutable_step.MutableStep"):
+        """
+        Method called right after all configuration values are read.
+        
+        Parameters
+        ----------
+        mutable_step : metaflow.user_decorators.mutable_step.MutableStep
+            A representation of this step
+        """
+        ...
+    def mutate(self, mutable_step: "metaflow.user_decorators.mutable_step.MutableStep"):
+        """
+        Method called right before the first Metaflow decorator is applied. This
+        means that the command line, including all `--with` options has been parsed.
+        
+        Parameters
+        ----------
+        mutable_step : metaflow.user_decorators.mutable_step.MutableStep
+            A representation of this step
+        """
+        ...
+    @classmethod
+    def __init_subclass__(cls_, **_kwargs):
+        ...
+    ...
+

{ob_metaflow_stubs-6.0.4.7.dist-info → ob_metaflow_stubs-6.0.4.8rc1.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: ob-metaflow-stubs
-Version: 6.0.4.7
+Version: 6.0.4.8rc1
 Summary: Metaflow Stubs: Stubs for the metaflow package
 Author: Netflix, Outerbounds & the Metaflow Community
 Author-email: help@outerbounds.co