ob-metaflow-stubs 6.0.3.188rc4__py2.py3-none-any.whl → 6.0.4.1__py2.py3-none-any.whl

metaflow-stubs/user_decorators/common.pyi

@@ -0,0 +1,38 @@
+######################################################################################################
+#                                 Auto-generated Metaflow stub file                                  #
+# MF version: 2.16.0.1+obcheckpoint(0.2.4);ob(v1)                                                    #
+# Generated on 2025-07-14T20:31:43.579879                                                            #
+######################################################################################################
+
+from __future__ import annotations
+
+import typing
+
+
+class ClassPath_Trie(object, metaclass=type):
+    def __init__(self):
+        ...
+    def init(self, initial_nodes: typing.Optional[typing.List[typing.Tuple[str, type]]] = None):
+        ...
+    def insert(self, classpath_name: str, value: type):
+        ...
+    def search(self, classpath_name: str) -> typing.Optional[type]:
+        ...
+    def remove(self, classpath_name: str):
+        ...
+    def unique_prefix_value(self, classpath_name: str) -> typing.Optional[type]:
+        ...
+    def unique_prefix_for_type(self, value: type) -> typing.Optional[str]:
+        ...
+    def get_unique_prefixes(self) -> typing.Dict[str, type]:
+        """
+        Get all unique prefixes in the trie.
+        
+        Returns
+        -------
+        List[str]
+            A list of unique prefixes.
+        """
+        ...
+    ...
+

metaflow-stubs/user_decorators/mutable_flow.pyi

@@ -0,0 +1,223 @@
+######################################################################################################
+#                                 Auto-generated Metaflow stub file                                  #
+# MF version: 2.16.0.1+obcheckpoint(0.2.4);ob(v1)                                                    #
+# Generated on 2025-07-14T20:31:43.579501                                                            #
+######################################################################################################
+
+from __future__ import annotations
+
+import typing
+if typing.TYPE_CHECKING:
+    import typing
+    import functools
+    import metaflow.user_decorators.mutable_step
+    import metaflow.user_configs.config_parameters
+    import metaflow.flowspec
+    import metaflow.parameters
+
+from ..exception import MetaflowException as MetaflowException
+from ..user_configs.config_parameters import ConfigValue as ConfigValue
+
+TYPE_CHECKING: bool
+
+class MutableFlow(object, metaclass=type):
+    def __init__(self, flow_spec: "metaflow.flowspec.FlowSpec", pre_mutate: bool = False, statically_defined: bool = False, inserted_by: typing.Optional[str] = None):
+        ...
+    @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 flow. 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 decorator specification to remove a decorator from the flow
+        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.
+        """
+        ...
+    @property
+    def configs(self) -> typing.Generator[typing.Tuple[str, metaflow.user_configs.config_parameters.ConfigValue], None, None]:
+        """
+        Iterate over all user configurations in this flow
+        
+        Use this to parameterize your flow based on configuration. As an example, the
+        `pre_mutate`/`mutate` methods can add decorators to steps in the flow that
+        depend on values in the configuration.
+        
+        ```
+        class MyDecorator(FlowMutator):
+            def mutate(flow: MutableFlow):
+                val = next(flow.configs)[1].steps.start.cpu
+                flow.start.add_decorator(environment, vars={'mycpu': val})
+                return flow
+        
+        @MyDecorator()
+        class TestFlow(FlowSpec):
+            config = Config('myconfig.json')
+        
+            @step
+            def start(self):
+                pass
+        ```
+        can be used to add an environment decorator to the `start` step.
+        
+        Yields
+        ------
+        Tuple[str, ConfigValue]
+            Iterates over the configurations of the flow
+        """
+        ...
+    @property
+    def parameters(self) -> typing.Generator[typing.Tuple[str, "metaflow.parameters.Parameter"], None, None]:
+        """
+        Iterate over all the parameters in this flow.
+        
+        Yields
+        ------
+        Tuple[str, Parameter]
+            Name of the parameter and parameter in the flow
+        """
+        ...
+    @property
+    def steps(self) -> typing.Generator[typing.Tuple[str, "metaflow.user_decorators.mutable_step.MutableStep"], None, None]:
+        """
+        Iterate over all the steps in this flow. The order of the steps
+        returned is not guaranteed.
+        
+        Yields
+        ------
+        Tuple[str, MutableStep]
+            A tuple with the step name and the step proxy
+        """
+        ...
+    def add_parameter(self, name: str, value: "metaflow.parameters.Parameter", overwrite: bool = False):
+        """
+        Add a parameter to the flow. You can only add parameters in the `pre_mutate`
+        method.
+        
+        Parameters
+        ----------
+        name : str
+            Name of the parameter
+        value : Parameter
+            Parameter to add to the flow
+        overwrite : bool, default False
+            If True, overwrite the parameter if it already exists
+        """
+        ...
+    def remove_parameter(self, parameter_name: str) -> bool:
+        """
+        Remove a parameter from the flow.
+        
+        The name given should match the name of the parameter (can be different
+        from the name of the parameter in the flow. You can not remove config parameters.
+        You can only remove parameters in the `pre_mutate` method.
+        
+        Parameters
+        ----------
+        parameter_name : str
+            Name of the parameter
+        
+        Returns
+        -------
+        bool
+            Returns True if the parameter was removed
+        """
+        ...
+    def add_decorator(self, deco_type: typing.Union[functools.partial, 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 flow-decorator to a flow. You can only add decorators in the
+        `pre_mutate` method.
+        
+        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 project
+        
+        ...
+        my_flow.add_decorator(project, deco_kwargs={"name":"my_project"})
+        ```
+        
+        is equivalent to:
+        ```
+        my_flow.add_decorator("project:name=my_project")
+        ```
+        
+        Note in the later case, there is no need to import the flow decorator.
+        
+        The latter syntax is useful to, for example, allow decorators to be stored as
+        strings in a configuration file.
+        
+        In terms of precedence for decorators:
+          - if a decorator can be applied multiple times all decorators
+            added are kept (this is rare for flow-decorators).
+          - if `duplicates` is set to `MutableFlow.IGNORE`, then the decorator
+            being added is ignored (in other words, the existing decorator has precedence).
+          - if `duplicates` is set to `MutableFlow.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 `MutableFlow.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, str]
+            The decorator class to add to this flow. If using a string, you cannot specify
+            additional arguments as all argument will be parsed from the decorator
+            specification.
+        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 MutableFlow.IGNORE
+            Instruction on how to handle duplicates. It can be one of:
+            - `MutableFlow.IGNORE`: Ignore the decorator if it already exists.
+            - `MutableFlow.ERROR`: Raise an error if the decorator already exists.
+            - `MutableFlow.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 flow-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 decorators 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.
+        """
+        ...
+    def __getattr__(self, name):
+        ...
+    ...
+

metaflow-stubs/user_decorators/mutable_step.pyi

@@ -0,0 +1,152 @@
+######################################################################################################
+#                                 Auto-generated Metaflow stub file                                  #
+# MF version: 2.16.0.1+obcheckpoint(0.2.4);ob(v1)                                                    #
+# Generated on 2025-07-14T20:31:43.580524                                                            #
+######################################################################################################
+
+from __future__ import annotations
+
+import typing
+if typing.TYPE_CHECKING:
+    import metaflow.user_decorator.mutable_flow
+    import typing
+    import metaflow.user_decorators.user_step_decorator
+    import functools
+    import metaflow.decorators
+    import metaflow.flowspec
+
+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.0.1+obcheckpoint(0.2.4);ob(v1)                                                    #
+# Generated on 2025-07-14T20:31:43.553233                                                            #
+######################################################################################################
+
+from __future__ import annotations
+
+import metaflow
+import typing
+if typing.TYPE_CHECKING:
+    import metaflow.decorators
+    import metaflow.flowspec
+    import metaflow.user_decorators.mutable_flow
+    import metaflow.user_decorators.user_flow_decorator
+
+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
+        """
+        ...
+    ...
+