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

metaflow-stubs/cards.pyi

@@ -1,19 +1,19 @@
 ##################################################################################
 #                       Auto-generated Metaflow stub file                        #
-# MF version: 2.12.22                                                            #
-# Generated on 2024-09-20T00:45:49.611483                                        #
+# MF version: 2.12.23                                                            #
+# Generated on 2024-10-01T14:32:39.972039                                        #
 ##################################################################################
 
 from __future__ import annotations
 
 import typing
 if typing.TYPE_CHECKING:
-    import metaflow.plugins.cards.card_modules.card
+    import metaflow.plugins.cards.card_modules.basic
+    import metaflow.plugins.cards.card_modules.components
     import metaflow.plugins.cards.card_client
     import metaflow
+    import metaflow.plugins.cards.card_modules.card
     import typing
-    import metaflow.plugins.cards.card_modules.components
-    import metaflow.plugins.cards.card_modules.basic
 
 def get_cards(task: typing.Union[str, "metaflow.Task"], id: typing.Optional[str] = None, type: typing.Optional[str] = None, follow_resumed: bool = True) -> metaflow.plugins.cards.card_client.CardContainer:
     """
@@ -64,6 +64,32 @@ class MetaflowCardComponent(object, metaclass=type):
     ...
 
 class MetaflowCard(object, metaclass=type):
+    """
+    Metaflow cards derive from this base class.
+    
+    Subclasses of this class are called *card types*. The desired card
+    type `T` is defined in the `@card` decorator as `@card(type=T)`.
+    
+    After a task with `@card(type=T, options=S)` finishes executing, Metaflow instantiates
+    a subclass `C` of `MetaflowCard` that has its `type` attribute set to `T`, i.e. `C.type=T`.
+    The constructor is given the options dictionary `S` that contains arbitrary
+    JSON-encodable data that is passed to the instance, parametrizing the card. The subclass
+    may override the constructor to capture and process the options.
+    
+    The subclass needs to implement a `render(task)` method that produces the card
+    contents in HTML, given the finished task that is represented by a `Task` object.
+    
+    Attributes
+    ----------
+    type : str
+        Card type string. Note that this should be a globally unique name, similar to a
+        Python package name, to avoid name clashes between different custom cards.
+    
+    Parameters
+    ----------
+    options : Dict
+        JSON-encodable dictionary containing user-definable options for the class.
+    """
     def __init__(self, options = {}, components = [], graph = None):
         ...
     def render(self, task: "metaflow.Task") -> str:
@@ -93,6 +119,26 @@ class MetaflowCard(object, metaclass=type):
     ...
 
 class Artifact(metaflow.plugins.cards.card_modules.components.UserComponent, metaclass=type):
+    """
+    A pretty-printed version of any Python object.
+    
+    Large objects are truncated using Python's built-in [`reprlib`](https://docs.python.org/3/library/reprlib.html).
+    
+    Example:
+    ```
+    from datetime import datetime
+    current.card.append(Artifact({'now': datetime.utcnow()}))
+    ```
+    
+    Parameters
+    ----------
+    artifact : object
+        Any Python object.
+    name : str, optional
+        Optional label for the object.
+    compressed : bool, default: True
+        Use a truncated representation.
+    """
     def update(self, artifact):
         ...
     def __init__(self, artifact: typing.Any, name: typing.Optional[str] = None, compressed: bool = True):
@@ -102,6 +148,45 @@ class Artifact(metaflow.plugins.cards.card_modules.components.UserComponent, met
     ...
 
 class Table(metaflow.plugins.cards.card_modules.components.UserComponent, metaclass=type):
+    """
+    A table.
+    
+    The contents of the table can be text or numerical data, a Pandas dataframe,
+    or other card components: `Artifact`, `Image`, `Markdown` objects.
+    
+    Example: Text and artifacts
+    ```
+    from metaflow.cards import Table, Artifact
+    current.card.append(
+        Table([
+            ['first row', Artifact({'a': 2})],
+            ['second row', Artifact(3)]
+        ])
+    )
+    ```
+    
+    Example: Table from a Pandas dataframe
+    ```
+    from metaflow.cards import Table
+    import pandas as pd
+    import numpy as np
+    current.card.append(
+        Table.from_dataframe(
+            pd.DataFrame(
+                np.random.randint(0, 100, size=(15, 4)),
+                columns=list("ABCD")
+            )
+        )
+    )
+    ```
+    
+    Parameters
+    ----------
+    data : List[List[str or MetaflowCardComponent]], optional
+        List (rows) of lists (columns). Each item can be a string or a `MetaflowCardComponent`.
+    headers : List[str], optional
+        Optional header row for the table.
+    """
     def update(self, *args, **kwargs):
         ...
     def __init__(self, data: typing.Optional[typing.List[typing.List[typing.Union[str, metaflow.plugins.cards.card_modules.card.MetaflowCardComponent]]]] = None, headers: typing.Optional[typing.List[str]] = None, disable_updates: bool = False):
@@ -124,6 +209,55 @@ class Table(metaflow.plugins.cards.card_modules.components.UserComponent, metacl
     ...
 
 class Image(metaflow.plugins.cards.card_modules.components.UserComponent, metaclass=type):
+    """
+    An image.
+    
+    `Images can be created directly from PNG/JPG/GIF `bytes`, `PIL.Image`s,
+    or Matplotlib figures. Note that the image data is embedded in the card,
+    so no external files are required to show the image.
+    
+    Example: Create an `Image` from bytes:
+    ```
+    current.card.append(
+        Image(
+            requests.get("https://www.gif-vif.com/hacker-cat.gif").content,
+            "Image From Bytes"
+        )
+    )
+    ```
+    
+    Example: Create an `Image` from a Matplotlib figure
+    ```
+    import pandas as pd
+    import numpy as np
+    current.card.append(
+        Image.from_matplotlib(
+            pandas.DataFrame(
+                np.random.randint(0, 100, size=(15, 4)),
+                columns=list("ABCD"),
+            ).plot()
+        )
+    )
+    ```
+    
+    Example: Create an `Image` from a [PIL](https://pillow.readthedocs.io/) Image
+    ```
+    from PIL import Image as PILImage
+    current.card.append(
+        Image.from_pil_image(
+            PILImage.fromarray(np.random.randn(1024, 768), "RGB"),
+            "From PIL Image"
+        )
+    )
+    ```
+    
+    Parameters
+    ----------
+    src : bytes
+        The image data in `bytes`.
+    label : str
+        Optional label for the image.
+    """
     @staticmethod
     def render_fail_headline(msg):
         ...
@@ -172,6 +306,30 @@ class Image(metaflow.plugins.cards.card_modules.components.UserComponent, metacl
     ...
 
 class Error(metaflow.plugins.cards.card_modules.components.UserComponent, metaclass=type):
+    """
+    This class helps visualize Error's on the `MetaflowCard`. It can help catch and print stack traces to errors that happen in `@step` code.
+    
+    ### Parameters
+    - `exception` (Exception) : The `Exception` to visualize. This value will be `repr`'d before passed down to `MetaflowCard`
+    - `title` (str) : The title that will appear over the visualized  `Exception`.
+    
+    ### Usage
+    ```python
+    @card
+    @step
+    def my_step(self):
+        from metaflow.cards import Error
+        from metaflow import current
+        try:
+            ...
+            ...
+        except Exception as e:
+            current.card.append(
+                Error(e,"Something misbehaved")
+            )
+        ...
+    ```
+    """
     def __init__(self, exception, title = None):
         ...
     def render(self, *args, **kwargs):
@@ -179,6 +337,21 @@ class Error(metaflow.plugins.cards.card_modules.components.UserComponent, metacl
     ...
 
 class Markdown(metaflow.plugins.cards.card_modules.components.UserComponent, metaclass=type):
+    """
+    A block of text formatted in Markdown.
+    
+    Example:
+    ```
+    current.card.append(
+        Markdown("# This is a header appended from `@step` code")
+    )
+    ```
+    
+    Parameters
+    ----------
+    text : str
+        Text formatted in Markdown.
+    """
     def update(self, text = None):
         ...
     def __init__(self, text = None):
@@ -208,6 +381,39 @@ class VegaChart(metaflow.plugins.cards.card_modules.components.UserComponent, me
     ...
 
 class ProgressBar(metaflow.plugins.cards.card_modules.components.UserComponent, metaclass=type):
+    """
+    A Progress bar for tracking progress of any task.
+    
+    Example:
+    ```
+    progress_bar = ProgressBar(
+        max=100,
+        label="Progress Bar",
+        value=0,
+        unit="%",
+        metadata="0.1 items/s"
+    )
+    current.card.append(
+        progress_bar
+    )
+    for i in range(100):
+        progress_bar.update(i, metadata="%s items/s" % i)
+    
+    ```
+    
+    Parameters
+    ----------
+    max : int
+        The maximum value of the progress bar.
+    label : str, optional
+        Optional label for the progress bar.
+    value : int, optional
+        Optional initial value of the progress bar.
+    unit : str, optional
+        Optional unit for the progress bar.
+    metadata : str, optional
+        Optional additional information to show on the progress bar.
+    """
     def __init__(self, max: int = 100, label: str = None, value: int = 0, unit: str = None, metadata: str = None):
         ...
     def update(self, new_value: int, metadata: str = None):

metaflow-stubs/cli.pyi

@@ -1,15 +1,35 @@
 ##################################################################################
 #                       Auto-generated Metaflow stub file                        #
-# MF version: 2.12.22                                                            #
-# Generated on 2024-09-20T00:45:49.624825                                        #
+# MF version: 2.12.23                                                            #
+# Generated on 2024-10-01T14:32:39.985591                                        #
 ##################################################################################
 
 from __future__ import annotations
 
 import typing
 if typing.TYPE_CHECKING:
-    import metaflow.exception
     import metaflow.metaflow_current
+    import metaflow.exception
+
+def get_metadata() -> str:
+    """
+    Returns the current Metadata provider.
+    
+    If this is not set explicitly using `metadata`, the default value is
+    determined through the Metaflow configuration. You can use this call to
+    check that your configuration is set up properly.
+    
+    If multiple configuration profiles are present, this call returns the one
+    selected through the `METAFLOW_PROFILE` environment variable.
+    
+    Returns
+    -------
+    str
+        Information about the Metadata provider currently selected. This information typically
+        returns provider specific information (like URL for remote providers or local paths for
+        local providers).
+    """
+    ...
 
 def namespace(ns: typing.Optional[str]) -> typing.Optional[str]:
     """

metaflow-stubs/client/__init__.pyi

@@ -1,15 +1,15 @@
 ##################################################################################
 #                       Auto-generated Metaflow stub file                        #
-# MF version: 2.12.22                                                            #
-# Generated on 2024-09-20T00:45:49.614630                                        #
+# MF version: 2.12.23                                                            #
+# Generated on 2024-10-01T14:32:39.975583                                        #
 ##################################################################################
 
 from __future__ import annotations
 
 import typing
 if typing.TYPE_CHECKING:
-    import typing
     import metaflow.client.core
+    import typing
     import metaflow.events
     import datetime
 
@@ -119,6 +119,19 @@ def default_metadata() -> str:
     ...
 
 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
@@ -170,6 +183,17 @@ class Metaflow(object, metaclass=type):
     ...
 
 class Flow(metaflow.client.core.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
@@ -256,6 +280,26 @@ class Flow(metaflow.client.core.MetaflowObject, metaclass=type):
     ...
 
 class Run(metaflow.client.core.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[metaflow.client.core.Step]:
         """
         [Legacy function - do not use]
@@ -488,6 +532,23 @@ class Run(metaflow.client.core.MetaflowObject, metaclass=type):
     ...
 
 class Step(metaflow.client.core.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[metaflow.client.core.Task]:
         """
@@ -622,6 +683,55 @@ class Step(metaflow.client.core.MetaflowObject, metaclass=type):
     ...
 
 class Task(metaflow.client.core.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
@@ -936,6 +1046,21 @@ class Task(metaflow.client.core.MetaflowObject, metaclass=type):
     ...
 
 class DataArtifact(metaflow.client.core.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:
         """