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

metaflow-stubs/plugins/cards/card_modules/card.pyi

@@ -1,7 +1,7 @@
 ##################################################################################
 #                       Auto-generated Metaflow stub file                        #
-# MF version: 2.12.22                                                            #
-# Generated on 2024-09-20T00:45:49.645888                                        #
+# MF version: 2.12.24                                                            #
+# Generated on 2024-10-04T11:37:47.012442                                        #
 ##################################################################################
 
 from __future__ import annotations
@@ -13,6 +13,32 @@ if typing.TYPE_CHECKING:
 TYPE_CHECKING: bool
 
 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:

metaflow-stubs/plugins/cards/card_modules/chevron/__init__.pyi

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

metaflow-stubs/plugins/cards/card_modules/chevron/main.pyi

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

metaflow-stubs/plugins/cards/card_modules/chevron/metadata.pyi

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

metaflow-stubs/plugins/cards/card_modules/chevron/renderer.pyi

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

metaflow-stubs/plugins/cards/card_modules/chevron/tokenizer.pyi

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

metaflow-stubs/plugins/cards/card_modules/components.pyi

@@ -1,16 +1,16 @@
 ##################################################################################
 #                       Auto-generated Metaflow stub file                        #
-# MF version: 2.12.22                                                            #
-# Generated on 2024-09-20T00:45:49.648121                                        #
+# MF version: 2.12.24                                                            #
+# Generated on 2024-10-04T11:37:47.014796                                        #
 ##################################################################################
 
 from __future__ import annotations
 
 import typing
 if typing.TYPE_CHECKING:
+    import metaflow.plugins.cards.card_modules.card
     import typing
     import metaflow.plugins.cards.card_modules.components
-    import metaflow.plugins.cards.card_modules.card
     import metaflow.plugins.cards.card_modules.basic
 
 class LogComponent(metaflow.plugins.cards.card_modules.basic.DefaultComponent, metaclass=type):
@@ -126,6 +126,26 @@ class StubComponent(UserComponent, metaclass=type):
     ...
 
 class Artifact(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):
@@ -135,6 +155,45 @@ class Artifact(UserComponent, metaclass=type):
     ...
 
 class Table(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):
@@ -157,6 +216,55 @@ class Table(UserComponent, metaclass=type):
     ...
 
 class Image(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):
         ...
@@ -205,6 +313,30 @@ class Image(UserComponent, metaclass=type):
     ...
 
 class Error(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):
@@ -212,6 +344,21 @@ class Error(UserComponent, metaclass=type):
     ...
 
 class Markdown(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):
@@ -221,6 +368,39 @@ class Markdown(UserComponent, metaclass=type):
     ...
 
 class ProgressBar(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/plugins/cards/card_modules/convert_to_native_type.pyi

@@ -1,13 +1,16 @@
 ##################################################################################
 #                       Auto-generated Metaflow stub file                        #
-# MF version: 2.12.22                                                            #
-# Generated on 2024-09-20T00:45:49.698344                                        #
+# MF version: 2.12.24                                                            #
+# Generated on 2024-10-04T11:37:47.065983                                        #
 ##################################################################################
 
 from __future__ import annotations
 
 
 class TypeResolvedObject(tuple, metaclass=type):
+    """
+    TypeResolvedObject(data, is_image, is_table)
+    """
     @staticmethod
     def __new__(_cls, data, is_image, is_table):
         """

metaflow-stubs/plugins/cards/card_modules/renderer_tools.pyi

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

metaflow-stubs/plugins/cards/card_modules/test_cards.pyi

@@ -1,7 +1,7 @@
 ##################################################################################
 #                       Auto-generated Metaflow stub file                        #
-# MF version: 2.12.22                                                            #
-# Generated on 2024-09-20T00:45:49.641429                                        #
+# MF version: 2.12.24                                                            #
+# Generated on 2024-10-04T11:37:47.007411                                        #
 ##################################################################################
 
 from __future__ import annotations
@@ -12,6 +12,32 @@ if typing.TYPE_CHECKING:
     import metaflow
 
 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:
@@ -132,6 +158,9 @@ class TestJSONComponent(metaflow.plugins.cards.card_modules.card.MetaflowCardCom
     ...
 
 class TestRefreshCard(metaflow.plugins.cards.card_modules.card.MetaflowCard, metaclass=type):
+    """
+    This card takes no components and helps test the `current.card.refresh(data)` interface.
+    """
     def render(self, task) -> str:
         ...
     def render_runtime(self, task, data):
@@ -141,6 +170,10 @@ class TestRefreshCard(metaflow.plugins.cards.card_modules.card.MetaflowCard, met
     ...
 
 class TestRefreshComponentCard(metaflow.plugins.cards.card_modules.card.MetaflowCard, metaclass=type):
+    """
+    This card takes components and helps test the `current.card.components["A"].update()`
+    interface
+    """
     def __init__(self, options = {}, components = [], graph = None):
         ...
     def render(self, task) -> str:

metaflow-stubs/plugins/cards/card_resolver.pyi

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

metaflow-stubs/plugins/cards/component_serializer.pyi

@@ -1,16 +1,16 @@
 ##################################################################################
 #                       Auto-generated Metaflow stub file                        #
-# MF version: 2.12.22                                                            #
-# Generated on 2024-09-20T00:45:49.680606                                        #
+# MF version: 2.12.24                                                            #
+# Generated on 2024-10-04T11:37:47.040282                                        #
 ##################################################################################
 
 from __future__ import annotations
 
 import typing
 if typing.TYPE_CHECKING:
-    import metaflow.plugins.cards.card_modules.components
-    import metaflow.exception
     import metaflow.plugins.cards.card_modules.card
+    import metaflow.exception
+    import metaflow.plugins.cards.card_modules.components
     import metaflow.plugins.cards.card_modules.basic
 
 class MetaflowCardComponent(object, metaclass=type):
@@ -83,6 +83,13 @@ class WarningComponent(metaflow.plugins.cards.card_modules.basic.ErrorComponent,
     ...
 
 class ComponentStore(object, metaclass=type):
+    """
+    The `ComponentStore` object helps store the components for a single card in memory.
+    This class has combination of a array/dictionary like interfaces to access/change the stored components.
+    
+    It exposes the `append` /`extend` methods (like an array) to add components.
+    It also exposes the `__getitem__`/`__setitem__` methods (like a dictionary) to access the components by their Ids.
+    """
     def __init__(self, logger, card_type = None, components = None, user_set_id = None):
         ...
     @property
@@ -118,6 +125,33 @@ class ComponentStore(object, metaclass=type):
     ...
 
 class CardComponentManager(object, metaclass=type):
+    """
+    This class manages the card's state for a single card.
+    - It uses the `ComponentStore` to manage the storage of the components
+    - It exposes methods to add, remove and access the components.
+    - It exposes a `refresh` method that will allow refreshing a card with new data
+    for realtime(ish) updates.
+    - The `CardComponentCollector` exposes convenience methods similar to this class for a default
+    editable card. These methods include :
+        - `append`
+        - `extend`
+        - `clear`
+        - `refresh`
+        - `components`
+        - `__iter__`
+    
+    ## Usage Patterns :
+    
+    ```python
+    current.card["mycardid"].append(component, id="comp123")
+    current.card["mycardid"].extend([component])
+    current.card["mycardid"].refresh(data) # refreshes the card with new data
+    current.card["mycardid"].components["comp123"] # returns the component with id "comp123"
+    current.card["mycardid"].components["comp123"].update()
+    current.card["mycardid"].components.clear() # Wipe all the components
+    del current.card["mycardid"].components["mycomponentid"] # Delete a component
+    ```
+    """
     def __init__(self, card_uuid, decorator_attributes, card_creator, components = None, logger = None, no_warnings = False, user_set_card_id = None, runtime_card = False, card_options = None, refresh_interval = 5):
         ...
     def append(self, component, id = None):
@@ -136,6 +170,25 @@ class CardComponentManager(object, metaclass=type):
     ...
 
 class CardComponentCollector(object, metaclass=type):
+    """
+    This class helps collect `MetaflowCardComponent`s during runtime execution
+    
+    ### Usage with `current`
+    `current.card` is of type `CardComponentCollector`
+    
+    ### Main Usage TLDR
+    - [x] `current.card.append` customizes the default editable card.
+    - [x] Only one card can be default editable in a step.
+    - [x] The card class must have `ALLOW_USER_COMPONENTS=True` to be considered default editable.
+        - [x] Classes with `ALLOW_USER_COMPONENTS=False` are never default editable.
+    - [x] The user can specify an `id` argument to a card, in which case the card is editable through `current.card[id].append`.
+        - [x] A card with an id can be also default editable, if there are no other cards that are eligible to be default editable.
+    - [x] If multiple default-editable cards exist but only one card doesn't have an id, the card without an id is considered to be default editable.
+    - [x] If we can't resolve a single default editable card through the above rules, `current.card`.append calls show a warning but the call doesn't fail.
+    - [x] A card that is not default editable can be still edited through:
+        - [x] its `current.card['myid']`
+        - [x] by looking it up by its type, e.g. `current.card.get(type='pytorch')`.
+    """
     def __init__(self, logger = None, card_creator = None):
         ...
     @staticmethod

metaflow-stubs/plugins/cards/exception.pyi

@@ -1,7 +1,7 @@
 ##################################################################################
 #                       Auto-generated Metaflow stub file                        #
-# MF version: 2.12.22                                                            #
-# Generated on 2024-09-20T00:45:49.678886                                        #
+# MF version: 2.12.24                                                            #
+# Generated on 2024-10-04T11:37:47.038307                                        #
 ##################################################################################
 
 from __future__ import annotations
@@ -20,6 +20,9 @@ class MetaflowException(Exception, metaclass=type):
 TYPE_CHECK_REGEX: str
 
 class CardClassFoundException(metaflow.exception.MetaflowException, metaclass=type):
+    """
+    This exception is raised with MetaflowCard class is not present for a particular card type.
+    """
     def __init__(self, card_name):
         ...
     ...
@@ -30,6 +33,9 @@ class TypeRequiredException(metaflow.exception.MetaflowException, metaclass=type
     ...
 
 class CardNotPresentException(metaflow.exception.MetaflowException, metaclass=type):
+    """
+    This exception is raised with a card is not present in the datastore.
+    """
     def __init__(self, pathspec, card_type = None, card_hash = None, card_id = None):
         ...
     ...

metaflow-stubs/plugins/catch_decorator.pyi

@@ -1,16 +1,16 @@
 ##################################################################################
 #                       Auto-generated Metaflow stub file                        #
-# MF version: 2.12.22                                                            #
-# Generated on 2024-09-20T00:45:49.631065                                        #
+# MF version: 2.12.24                                                            #
+# Generated on 2024-10-04T11:37:46.998318                                        #
 ##################################################################################
 
 from __future__ import annotations
 
 import typing
 if typing.TYPE_CHECKING:
-    import metaflow.exception
     import metaflow.metaflow_current
     import metaflow.decorators
+    import metaflow.exception
 
 class MetaflowException(Exception, metaclass=type):
     def __init__(self, msg = "", lineno = None):
@@ -44,6 +44,23 @@ class FailureHandledByCatch(metaflow.exception.MetaflowException, metaclass=type
     ...
 
 class CatchDecorator(metaflow.decorators.StepDecorator, metaclass=type):
+    """
+    Specifies that the step will success under all circumstances.
+    
+    The decorator will create an optional artifact, specified by `var`, which
+    contains the exception raised. You can use it to detect the presence
+    of errors, indicating that all happy-path artifacts produced by the step
+    are missing.
+    
+    Parameters
+    ----------
+    var : str, optional, default None
+        Name of the artifact in which to store the caught exception.
+        If not specified, the exception is not stored.
+    print_exception : bool, default True
+        Determines whether or not the exception is printed to
+        stdout when caught.
+    """
     def step_init(self, flow, graph, step, decos, environment, flow_datastore, logger):
         ...
     def task_exception(self, exception, step, flow, graph, retry_count, max_user_code_retries):