metaflow-stubs 2.12.22__py2.py3-none-any.whl → 2.12.24__py2.py3-none-any.whl

metaflow-stubs/client/core.pyi

@@ -1,25 +1,28 @@
 ##################################################################################
 #                       Auto-generated Metaflow stub file                        #
-# MF version: 2.12.22                                                            #
-# Generated on 2024-09-20T00:45:49.597112                                        #
+# MF version: 2.12.24                                                            #
+# Generated on 2024-10-04T11:37:46.961233                                        #
 ##################################################################################
 
 from __future__ import annotations
 
 import typing
 if typing.TYPE_CHECKING:
-    import metaflow.events
+    import metaflow.metaflow_current
     import metaflow.client.core
+    import datetime
     import metaflow.exception
-    import metaflow.metaflow_current
-    import metaflow
     import typing
     import tarfile
-    import datetime
+    import metaflow.events
+    import metaflow
 
 current: metaflow.metaflow_current.Current
 
 class Trigger(object, metaclass=type):
+    """
+    Defines a container of event triggers' metadata.
+    """
     def __init__(self, _meta = None):
         ...
     @classmethod
@@ -174,6 +177,9 @@ class FileCache(object, metaclass=type):
     ...
 
 class Metadata(tuple, metaclass=type):
+    """
+    Metadata(name, value, created_at, type, task)
+    """
     @staticmethod
     def __new__(_cls, name, value, created_at, type, task):
         """
@@ -304,6 +310,45 @@ def default_namespace() -> str:
     ...
 
 class MetaflowObject(object, metaclass=type):
+    """
+    Base class for all Metaflow objects.
+    
+    Creates a new object of a specific type (Flow, Run, Step, Task, DataArtifact) given
+    a path to it (its `pathspec`).
+    
+    Accessing Metaflow objects is done through one of two methods:
+      - either by directly instantiating it with this class
+      - or by accessing it through its parent (iterating over
+        all children or accessing directly using the [] operator)
+    
+    With this class, you can:
+      - Get a `Flow`; use `Flow('FlowName')`.
+      - Get a `Run` of a flow; use `Run('FlowName/RunID')`.
+      - Get a `Step` of a run; use `Step('FlowName/RunID/StepName')`.
+      - Get a `Task` of a step, use `Task('FlowName/RunID/StepName/TaskID')`
+      - Get a `DataArtifact` of a task; use
+           `DataArtifact('FlowName/RunID/StepName/TaskID/ArtifactName')`.
+    
+    Attributes
+    ----------
+    tags : FrozenSet[str]
+        Tags associated with the run this object belongs to (user and system tags).
+    user_tags: FrozenSet[str]
+        User tags associated with the run this object belongs to.
+    system_tags: FrozenSet[str]
+        System tags associated with the run this object belongs to.
+    created_at : datetime
+        Date and time this object was first created.
+    parent : MetaflowObject
+        Parent of this object. The parent of a `Run` is a `Flow` for example
+    pathspec : str
+        Pathspec of this object (for example: 'FlowName/RunID' for a `Run`)
+    path_components : List[str]
+        Components of the pathspec
+    origin_pathspec : str, optional
+        Pathspec of the original object this object was cloned from (in the case of a resume).
+        None if not applicable.
+    """
     def __init__(self, pathspec: typing.Optional[str] = None, attempt: typing.Optional[int] = None, _object: typing.Optional["MetaflowObject"] = None, _parent: typing.Optional["MetaflowObject"] = None, _namespace_check: bool = True, _current_namespace: typing.Optional[str] = None):
         ...
     def __iter__(self) -> typing.Iterator["MetaflowObject"]:
@@ -487,6 +532,30 @@ class MetaflowObject(object, metaclass=type):
     ...
 
 class MetaflowCode(object, metaclass=type):
+    """
+    Snapshot of the code used to execute this `Run`. Instantiate the object through
+    `Run(...).code` (if any step is executed remotely) or `Task(...).code` for an
+    individual task. The code package is the same for all steps of a `Run`.
+    
+    `MetaflowCode` includes a package of the user-defined `FlowSpec` class and supporting
+    files, as well as a snapshot of the Metaflow library itself.
+    
+    Currently, `MetaflowCode` objects are stored only for `Run`s that have at least one `Step`
+    executing outside the user's local environment.
+    
+    The `TarFile` for the `Run` is given by `Run(...).code.tarball`
+    
+    Attributes
+    ----------
+    path : str
+        Location (in the datastore provider) of the code package.
+    info : Dict[str, str]
+        Dictionary of information related to this code-package.
+    flowspec : str
+        Source code of the file containing the `FlowSpec` in this code package.
+    tarball : TarFile
+        Python standard library `tarfile.TarFile` archive containing all the code.
+    """
     def __init__(self, flow_name: str, code_package: str):
         ...
     @property
@@ -538,6 +607,21 @@ class MetaflowCode(object, metaclass=type):
     ...
 
 class DataArtifact(MetaflowObject, metaclass=type):
+    """
+    A single data artifact and associated metadata. Note that this object does
+    not contain other objects as it is the leaf object in the hierarchy.
+    
+    Attributes
+    ----------
+    data : object
+        The data contained in this artifact, that is, the object produced during
+        execution of this run.
+    sha : string
+        A unique ID of this artifact.
+    finished_at : datetime
+        Corresponds roughly to the `Task.finished_at` time of the parent `Task`.
+        An alias for `DataArtifact.created_at`.
+    """
     @property
     def data(self) -> typing.Any:
         """
@@ -594,6 +678,32 @@ class DataArtifact(MetaflowObject, metaclass=type):
     ...
 
 class MetaflowData(object, metaclass=type):
+    """
+    Container of data artifacts produced by a `Task`. This object is
+    instantiated through `Task.data`.
+    
+    `MetaflowData` allows results to be retrieved by their name
+    through a convenient dot notation:
+    
+    ```python
+    Task(...).data.my_object
+    ```
+    
+    You can also test the existence of an object
+    
+    ```python
+    if 'my_object' in Task(...).data:
+        print('my_object found')
+    ```
+    
+    Note that this container relies on the local cache to load all data
+    artifacts. If your `Task` contains a lot of data, a more efficient
+    approach is to load artifacts individually like so
+    
+    ```
+    Task(...)['my_object'].data
+    ```
+    """
     def __init__(self, artifacts: typing.Iterable[DataArtifact]):
         ...
     def __getattr__(self, name: str):
@@ -607,6 +717,55 @@ class MetaflowData(object, metaclass=type):
     ...
 
 class Task(MetaflowObject, metaclass=type):
+    """
+    A `Task` represents an execution of a `Step`.
+    
+    It contains all `DataArtifact` objects produced by the task as
+    well as metadata related to execution.
+    
+    Note that the `@retry` decorator may cause multiple attempts of
+    the task to be present. Usually you want the latest attempt, which
+    is what instantiating a `Task` object returns by default. If
+    you need to e.g. retrieve logs from a failed attempt, you can
+    explicitly get information about a specific attempt by using the
+    following syntax when creating a task:
+    
+    `Task('flow/run/step/task', attempt=<attempt>)`
+    
+    where `attempt=0` corresponds to the first attempt etc.
+    
+    Attributes
+    ----------
+    metadata : List[Metadata]
+        List of all metadata events associated with the task.
+    metadata_dict : Dict[str, str]
+        A condensed version of `metadata`: A dictionary where keys
+        are names of metadata events and values the latest corresponding event.
+    data : MetaflowData
+        Container of all data artifacts produced by this task. Note that this
+        call downloads all data locally, so it can be slower than accessing
+        artifacts individually. See `MetaflowData` for more information.
+    artifacts : MetaflowArtifacts
+        Container of `DataArtifact` objects produced by this task.
+    successful : bool
+        True if the task completed successfully.
+    finished : bool
+        True if the task completed.
+    exception : object
+        Exception raised by this task if there was one.
+    finished_at : datetime
+        Time this task finished.
+    runtime_name : str
+        Runtime this task was executed on.
+    stdout : str
+        Standard output for the task execution.
+    stderr : str
+        Standard error output for the task execution.
+    code : MetaflowCode
+        Code package for this task (if present). See `MetaflowCode`.
+    environment_info : Dict[str, str]
+        Information about the execution environment.
+    """
     def __init__(self, *args, **kwargs):
         ...
     @property
@@ -921,6 +1080,23 @@ class Task(MetaflowObject, metaclass=type):
     ...
 
 class Step(MetaflowObject, metaclass=type):
+    """
+    A `Step` represents a user-defined step, that is, a method annotated with the `@step` decorator.
+    
+    It contains `Task` objects associated with the step, that is, all executions of the
+    `Step`. The step may contain multiple `Task`s in the case of a foreach step.
+    
+    Attributes
+    ----------
+    task : Task
+        The first `Task` object in this step. This is a shortcut for retrieving the only
+        task contained in a non-foreach step.
+    finished_at : datetime
+        Time when the latest `Task` of this step finished. Note that in the case of foreaches,
+        this time may change during execution of the step.
+    environment_info : Dict[str, Any]
+        Information about the execution environment.
+    """
     @property
     def task(self) -> typing.Optional[Task]:
         """
@@ -1055,6 +1231,26 @@ class Step(MetaflowObject, metaclass=type):
     ...
 
 class Run(MetaflowObject, metaclass=type):
+    """
+    A `Run` represents an execution of a `Flow`. It is a container of `Step`s.
+    
+    Attributes
+    ----------
+    data : MetaflowData
+        a shortcut to run['end'].task.data, i.e. data produced by this run.
+    successful : bool
+        True if the run completed successfully.
+    finished : bool
+        True if the run completed.
+    finished_at : datetime
+        Time this run finished.
+    code : MetaflowCode
+        Code package for this run (if present). See `MetaflowCode`.
+    trigger : MetaflowTrigger
+        Information about event(s) that triggered this run (if present). See `MetaflowTrigger`.
+    end_task : Task
+        `Task` for the end step (if it is present already).
+    """
     def steps(self, *tags: str) -> typing.Iterator[Step]:
         """
         [Legacy function - do not use]
@@ -1287,6 +1483,17 @@ class Run(MetaflowObject, metaclass=type):
     ...
 
 class Flow(MetaflowObject, metaclass=type):
+    """
+    A Flow represents all existing flows with a certain name, in other words,
+    classes derived from `FlowSpec`. A container of `Run` objects.
+    
+    Attributes
+    ----------
+    latest_run : Run
+        Latest `Run` (in progress or completed, successfully or not) of this flow.
+    latest_successful_run : Run
+        Latest successfully completed `Run` of this flow.
+    """
     def __init__(self, *args, **kwargs):
         ...
     @property
@@ -1373,6 +1580,19 @@ class Flow(MetaflowObject, metaclass=type):
     ...
 
 class Metaflow(object, metaclass=type):
+    """
+    Entry point to all objects in the Metaflow universe.
+    
+    This object can be used to list all the flows present either through the explicit property
+    or by iterating over this object.
+    
+    Attributes
+    ----------
+    flows : List[Flow]
+        Returns the list of all `Flow` objects known to this metadata provider. Note that only
+        flows present in the current namespace will be returned. A `Flow` is present in a namespace
+        if it has at least one run in the namespace.
+    """
     def __init__(self):
         ...
     @property

metaflow-stubs/client/filecache.pyi

@@ -1,15 +1,15 @@
 ##################################################################################
 #                       Auto-generated Metaflow stub file                        #
-# MF version: 2.12.22                                                            #
-# Generated on 2024-09-20T00:45:49.625922                                        #
+# MF version: 2.12.24                                                            #
+# Generated on 2024-10-04T11:37:46.991298                                        #
 ##################################################################################
 
 from __future__ import annotations
 
 import typing
 if typing.TYPE_CHECKING:
-    import metaflow.exception
     import metaflow.datastore.content_addressed_store
+    import metaflow.exception
 
 class MetaflowException(Exception, metaclass=type):
     def __init__(self, msg = "", lineno = None):

metaflow-stubs/clone_util.pyi

@@ -1,13 +1,16 @@
 ##################################################################################
 #                       Auto-generated Metaflow stub file                        #
-# MF version: 2.12.22                                                            #
-# Generated on 2024-09-20T00:45:49.623378                                        #
+# MF version: 2.12.24                                                            #
+# Generated on 2024-10-04T11:37:46.988641                                        #
 ##################################################################################
 
 from __future__ import annotations
 
 
 class MetaDatum(tuple, metaclass=type):
+    """
+    MetaDatum(field, value, type, tags)
+    """
     @staticmethod
     def __new__(_cls, field, value, type, tags):
         """

metaflow-stubs/events.pyi

@@ -1,19 +1,34 @@
 ##################################################################################
 #                       Auto-generated Metaflow stub file                        #
-# MF version: 2.12.22                                                            #
-# Generated on 2024-09-20T00:45:49.599428                                        #
+# MF version: 2.12.24                                                            #
+# Generated on 2024-10-04T11:37:46.963827                                        #
 ##################################################################################
 
 from __future__ import annotations
 
 import typing
 if typing.TYPE_CHECKING:
-    import metaflow.events
     import metaflow
+    import metaflow.events
 
 TYPE_CHECKING: bool
 
 class MetaflowEvent(tuple, metaclass=type):
+    """
+    Container of metadata that identifies the event that triggered
+    the `Run` under consideration.
+    
+    Attributes
+    ----------
+    name : str
+        name of the event.
+    id : str
+        unique identifier for the event.
+    timestamp : datetime
+        timestamp recording creation time for the event.
+    type : str
+        type for the event - one of `event` or `run`
+    """
     @staticmethod
     def __new__(_cls, name, id, timestamp, type):
         """
@@ -33,6 +48,9 @@ class MetaflowEvent(tuple, metaclass=type):
     ...
 
 class Trigger(object, metaclass=type):
+    """
+    Defines a container of event triggers' metadata.
+    """
     def __init__(self, _meta = None):
         ...
     @classmethod

metaflow-stubs/exception.pyi

@@ -1,7 +1,7 @@
 ##################################################################################
 #                       Auto-generated Metaflow stub file                        #
-# MF version: 2.12.22                                                            #
-# Generated on 2024-09-20T00:45:49.587431                                        #
+# MF version: 2.12.24                                                            #
+# Generated on 2024-10-04T11:37:46.950745                                        #
 ##################################################################################
 
 from __future__ import annotations

metaflow-stubs/flowspec.pyi

@@ -1,21 +1,33 @@
 ##################################################################################
 #                       Auto-generated Metaflow stub file                        #
-# MF version: 2.12.22                                                            #
-# Generated on 2024-09-20T00:45:49.598724                                        #
+# MF version: 2.12.24                                                            #
+# Generated on 2024-10-04T11:37:46.963083                                        #
 ##################################################################################
 
 from __future__ import annotations
 
 import typing
 if typing.TYPE_CHECKING:
-    import metaflow.flowspec
-    import metaflow.exception
-    import metaflow.unbounded_foreach
     import metaflow.datastore.inputs
+    import metaflow.exception
     import typing
+    import metaflow.unbounded_foreach
+    import metaflow.flowspec
     import metaflow.parameters
 
 class DelayedEvaluationParameter(object, metaclass=type):
+    """
+    This is a very simple wrapper to allow parameter "conversion" to be delayed until
+    the `_set_constants` function in FlowSpec. Typically, parameters are converted
+    by click when the command line option is processed. For some parameters, like
+    IncludeFile, this is too early as it would mean we would trigger the upload
+    of the file too early. If a parameter converts to a DelayedEvaluationParameter
+    object through the usual click mechanisms, `_set_constants` knows to invoke the
+    __call__ method on that DelayedEvaluationParameter; in that case, the __call__
+    method is invoked without any parameter. The return_str parameter will be used
+    by schedulers when they need to convert DelayedEvaluationParameters to a
+    string to store them
+    """
     def __init__(self, name, field, fun):
         ...
     def __call__(self, return_str = False):
@@ -23,6 +35,49 @@ class DelayedEvaluationParameter(object, metaclass=type):
     ...
 
 class Parameter(object, metaclass=type):
+    """
+    Defines a parameter for a flow.
+    
+    Parameters must be instantiated as class variables in flow classes, e.g.
+    ```
+    class MyFlow(FlowSpec):
+        param = Parameter('myparam')
+    ```
+    in this case, the parameter is specified on the command line as
+    ```
+    python myflow.py run --myparam=5
+    ```
+    and its value is accessible through a read-only artifact like this:
+    ```
+    print(self.param == 5)
+    ```
+    Note that the user-visible parameter name, `myparam` above, can be
+    different from the artifact name, `param` above.
+    
+    The parameter value is converted to a Python type based on the `type`
+    argument or to match the type of `default`, if it is set.
+    
+    Parameters
+    ----------
+    name : str
+        User-visible parameter name.
+    default : str or float or int or bool or `JSONType` or a function.
+        Default value for the parameter. Use a special `JSONType` class to
+        indicate that the value must be a valid JSON object. A function
+        implies that the parameter corresponds to a *deploy-time parameter*.
+        The type of the default value is used as the parameter `type`.
+    type : Type, default None
+        If `default` is not specified, define the parameter type. Specify
+        one of `str`, `float`, `int`, `bool`, or `JSONType`. If None, defaults
+        to the type of `default` or `str` if none specified.
+    help : str, optional
+        Help text to show in `run --help`.
+    required : bool, default False
+        Require that the user specified a value for the parameter.
+        `required=True` implies that the `default` is not used.
+    show_default : bool, default True
+        If True, show the default value in the help text.
+    """
     def __init__(self, name: str, default: typing.Union[str, float, int, bool, typing.Dict[str, typing.Any], typing.Callable[[], typing.Union[str, float, int, bool, typing.Dict[str, typing.Any]]], None] = None, type: typing.Union[typing.Type[str], typing.Type[float], typing.Type[int], typing.Type[bool], metaflow.parameters.JSONTypeClass, None] = None, help: typing.Optional[str] = None, required: bool = False, show_default: bool = True, **kwargs: typing.Dict[str, typing.Any]):
         ...
     def __repr__(self):
@@ -69,6 +124,9 @@ class InvalidNextException(metaflow.exception.MetaflowException, metaclass=type)
     ...
 
 class ParallelUBF(metaflow.unbounded_foreach.UnboundedForeachInput, metaclass=type):
+    """
+    Unbounded-for-each placeholder for supporting parallel (multi-node) steps.
+    """
     def __init__(self, num_parallel):
         ...
     def __getitem__(self, item):
@@ -76,6 +134,14 @@ class ParallelUBF(metaflow.unbounded_foreach.UnboundedForeachInput, metaclass=ty
     ...
 
 class FlowSpec(object, metaclass=_FlowSpecMeta):
+    """
+    Main class from which all Flows should inherit.
+    
+    Attributes
+    ----------
+    index
+    input
+    """
     def __init__(self, use_cli = True):
         """
         Construct a FlowSpec

metaflow-stubs/generated_for.txt

@@ -1 +1 @@
-2.12.22 2024-09-20T00:45:49.569338
+2.12.24 2024-10-04T11:37:46.932011