ob-metaflow-stubs 6.0.3.103rc3__py2.py3-none-any.whl → 6.0.3.105__py2.py3-none-any.whl

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

@@ -1,7 +1,7 @@
 ##################################################################################
 #                       Auto-generated Metaflow stub file                        #
-# MF version: 2.12.22.1+obcheckpoint(0.0.11);ob(v1)                              #
-# Generated on 2024-09-20T21:42:44.567091                                        #
+# MF version: 2.12.24.1+obcheckpoint(0.0.11);ob(v1)                              #
+# Generated on 2024-10-04T10:13:10.658445                                        #
 ##################################################################################
 
 from __future__ import annotations
@@ -9,8 +9,8 @@ from __future__ import annotations
 import typing
 if typing.TYPE_CHECKING:
     import metaflow.plugins.cards.card_modules.basic
-    import typing
     import metaflow.plugins.cards.card_modules.components
+    import typing
     import metaflow.plugins.cards.card_modules.card
 
 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.1+obcheckpoint(0.0.11);ob(v1)                              #
-# Generated on 2024-09-20T21:42:44.589270                                        #
+# MF version: 2.12.24.1+obcheckpoint(0.0.11);ob(v1)                              #
+# Generated on 2024-10-04T10:13:10.681152                                        #
 ##################################################################################
 
 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.1+obcheckpoint(0.0.11);ob(v1)                              #
-# Generated on 2024-09-20T21:42:44.589483                                        #
+# MF version: 2.12.24.1+obcheckpoint(0.0.11);ob(v1)                              #
+# Generated on 2024-10-04T10:13:10.681327                                        #
 ##################################################################################
 
 from __future__ import annotations

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

@@ -1,17 +1,43 @@
 ##################################################################################
 #                       Auto-generated Metaflow stub file                        #
-# MF version: 2.12.22.1+obcheckpoint(0.0.11);ob(v1)                              #
-# Generated on 2024-09-20T21:42:44.582909                                        #
+# MF version: 2.12.24.1+obcheckpoint(0.0.11);ob(v1)                              #
+# Generated on 2024-10-04T10:13:10.674794                                        #
 ##################################################################################
 
 from __future__ import annotations
 
 import typing
 if typing.TYPE_CHECKING:
-    import metaflow.plugins.cards.card_modules.card
     import metaflow
+    import metaflow.plugins.cards.card_modules.card
 
 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.1+obcheckpoint(0.0.11);ob(v1)                              #
-# Generated on 2024-09-20T21:42:44.587616                                        #
+# MF version: 2.12.24.1+obcheckpoint(0.0.11);ob(v1)                              #
+# Generated on 2024-10-04T10:13:10.679452                                        #
 ##################################################################################
 
 from __future__ import annotations

metaflow-stubs/plugins/cards/component_serializer.pyi

@@ -1,7 +1,7 @@
 ##################################################################################
 #                       Auto-generated Metaflow stub file                        #
-# MF version: 2.12.22.1+obcheckpoint(0.0.11);ob(v1)                              #
-# Generated on 2024-09-20T21:42:44.605551                                        #
+# MF version: 2.12.24.1+obcheckpoint(0.0.11);ob(v1)                              #
+# Generated on 2024-10-04T10:13:10.685946                                        #
 ##################################################################################
 
 from __future__ import annotations
@@ -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.1+obcheckpoint(0.0.11);ob(v1)                              #
-# Generated on 2024-09-20T21:42:44.588921                                        #
+# MF version: 2.12.24.1+obcheckpoint(0.0.11);ob(v1)                              #
+# Generated on 2024-10-04T10:13:10.680776                                        #
 ##################################################################################
 
 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,15 +1,15 @@
 ##################################################################################
 #                       Auto-generated Metaflow stub file                        #
-# MF version: 2.12.22.1+obcheckpoint(0.0.11);ob(v1)                              #
-# Generated on 2024-09-20T21:42:44.576386                                        #
+# MF version: 2.12.24.1+obcheckpoint(0.0.11);ob(v1)                              #
+# Generated on 2024-10-04T10:13:10.669411                                        #
 ##################################################################################
 
 from __future__ import annotations
 
 import typing
 if typing.TYPE_CHECKING:
-    import metaflow.metaflow_current
     import metaflow.exception
+    import metaflow.metaflow_current
     import metaflow.decorators
 
 class MetaflowException(Exception, metaclass=type):
@@ -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):

metaflow-stubs/plugins/datatools/__init__.pyi

@@ -1,7 +1,7 @@
 ##################################################################################
 #                       Auto-generated Metaflow stub file                        #
-# MF version: 2.12.22.1+obcheckpoint(0.0.11);ob(v1)                              #
-# Generated on 2024-09-20T21:42:44.578189                                        #
+# MF version: 2.12.24.1+obcheckpoint(0.0.11);ob(v1)                              #
+# Generated on 2024-10-04T10:13:10.670609                                        #
 ##################################################################################
 
 from __future__ import annotations
@@ -9,8 +9,8 @@ from __future__ import annotations
 import typing
 if typing.TYPE_CHECKING:
     import io
-    import metaflow.exception
     import metaflow.plugins.datatools.s3.s3
+    import metaflow.exception
 
 def read_in_chunks(dst, src, src_sz, max_chunk_size):
     ...
@@ -22,6 +22,13 @@ class MetaflowLocalURLException(metaflow.exception.MetaflowException, metaclass=
     ...
 
 class Local(object, metaclass=type):
+    """
+    This class allows you to access the local filesystem in a way similar to the S3 datatools
+    client. It is a stripped down version for now and only implements the functionality needed
+    for this use case.
+    
+    In the future, we may want to allow it to be used in a way similar to the S3() client.
+    """
     @classmethod
     def get_root_from_config(cls, echo, create_on_absent = True):
         ...
@@ -47,6 +54,59 @@ class MetaflowS3Exception(metaflow.exception.MetaflowException, metaclass=type):
     ...
 
 class S3(object, metaclass=type):
+    """
+    The Metaflow S3 client.
+    
+    This object manages the connection to S3 and a temporary diretory that is used
+    to download objects. Note that in most cases when the data fits in memory, no local
+    disk IO is needed as operations are cached by the operating system, which makes
+    operations fast as long as there is enough memory available.
+    
+    The easiest way is to use this object as a context manager:
+    ```
+    with S3() as s3:
+        data = [obj.blob for obj in s3.get_many(urls)]
+    print(data)
+    ```
+    The context manager takes care of creating and deleting a temporary directory
+    automatically. Without a context manager, you must call `.close()` to delete
+    the directory explicitly:
+    ```
+    s3 = S3()
+    data = [obj.blob for obj in s3.get_many(urls)]
+    s3.close()
+    ```
+    You can customize the location of the temporary directory with `tmproot`. It
+    defaults to the current working directory.
+    
+    To make it easier to deal with object locations, the client can be initialized
+    with an S3 path prefix. There are three ways to handle locations:
+    
+    1. Use a `metaflow.Run` object or `self`, e.g. `S3(run=self)` which
+       initializes the prefix with the global `DATATOOLS_S3ROOT` path, combined
+       with the current run ID. This mode makes it easy to version data based
+       on the run ID consistently. You can use the `bucket` and `prefix` to
+       override parts of `DATATOOLS_S3ROOT`.
+    
+    2. Specify an S3 prefix explicitly with `s3root`,
+       e.g. `S3(s3root='s3://mybucket/some/path')`.
+    
+    3. Specify nothing, i.e. `S3()`, in which case all operations require
+       a full S3 url prefixed with `s3://`.
+    
+    Parameters
+    ----------
+    tmproot : str, default: '.'
+        Where to store the temporary directory.
+    bucket : str, optional
+        Override the bucket from `DATATOOLS_S3ROOT` when `run` is specified.
+    prefix : str, optional
+        Override the path from `DATATOOLS_S3ROOT` when `run` is specified.
+    run : FlowSpec or Run, optional
+        Derive path prefix from the current or a past run ID, e.g. S3(run=self).
+    s3root : str, optional
+        If `run` is not specified, use this as the S3 prefix.
+    """
     @classmethod
     def get_root_from_config(cls, echo, create_on_absent = True):
         ...

metaflow-stubs/plugins/datatools/local.pyi

@@ -1,7 +1,7 @@
 ##################################################################################
 #                       Auto-generated Metaflow stub file                        #
-# MF version: 2.12.22.1+obcheckpoint(0.0.11);ob(v1)                              #
-# Generated on 2024-09-20T21:42:44.571015                                        #
+# MF version: 2.12.24.1+obcheckpoint(0.0.11);ob(v1)                              #
+# Generated on 2024-10-04T10:13:10.662566                                        #
 ##################################################################################
 
 from __future__ import annotations
@@ -28,6 +28,13 @@ class MetaflowLocalNotFound(metaflow.exception.MetaflowException, metaclass=type
     ...
 
 class LocalObject(object, metaclass=type):
+    """
+    This object represents a local object. It is a very thin wrapper
+    to allow it to be used in the same way as the S3Object (only as needed
+    in the IncludeFile use case)
+    
+    Get or list calls return one or more of LocalObjects.
+    """
     def __init__(self, url, path):
         ...
     @property
@@ -59,6 +66,13 @@ class LocalObject(object, metaclass=type):
     ...
 
 class Local(object, metaclass=type):
+    """
+    This class allows you to access the local filesystem in a way similar to the S3 datatools
+    client. It is a stripped down version for now and only implements the functionality needed
+    for this use case.
+    
+    In the future, we may want to allow it to be used in a way similar to the S3() client.
+    """
     @classmethod
     def get_root_from_config(cls, echo, create_on_absent = True):
         ...