ob-metaflow 2.10.7.4__py2.py3-none-any.whl → 2.10.9.2__py2.py3-none-any.whl

metaflow/plugins/cards/card_cli.py

@@ -1,11 +1,17 @@
 from metaflow.client import Task
 from metaflow import JSONType, namespace
-from metaflow.exception import CommandException
+from metaflow.util import resolve_identity
+from metaflow.exception import (
+    CommandException,
+    MetaflowNotFound,
+    MetaflowNamespaceMismatch,
+)
 import webbrowser
 import re
 from metaflow._vendor import click
 import os
 import json
+import uuid
 import signal
 import random
 from contextlib import contextmanager
@@ -19,11 +25,18 @@ from .exception import (
     CardNotPresentException,
     TaskNotFoundException,
 )
+import traceback
+from collections import namedtuple
 
 from .card_resolver import resolve_paths_from_task, resumed_info
 
 id_func = id
 
+CardRenderInfo = namedtuple(
+    "CardRenderInfo",
+    ["mode", "is_implemented", "data", "timed_out", "timeout_stack_trace"],
+)
+
 
 def open_in_browser(card_path):
     url = "file://" + os.path.abspath(card_path)
@@ -151,8 +164,6 @@ def timeout(time):
 
     try:
         yield
-    except TimeoutError:
-        pass
     finally:
         # Unregister the signal so that it won't be triggered
         # if the timeout is not reached.
@@ -375,14 +386,144 @@ def card_read_options_and_arguments(func):
     return wrapper
 
 
-def render_card(mf_card, task, timeout_value=None):
-    rendered_info = None
+def update_card(mf_card, mode, task, data, timeout_value=None):
+    """
+    This method will be responsible for creating a card/data-update based on the `mode`.
+    There are three possible modes taken by this function.
+        - render :
+            - This will render the "final" card.
+            - This mode is passed at task completion.
+            - Setting this mode will call the `render` method of a MetaflowCard.
+            - It will result in the creation of an HTML page.
+        - render_runtime:
+            - Setting this mode will render a card during task "runtime".
+            - Setting this mode will call the `render_runtime` method of a MetaflowCard.
+            - It will result in the creation of an HTML page.
+        - refresh:
+            - Setting this mode will refresh the data update for a card.
+            - We support this mode because rendering a full card can be an expensive operation, but shipping tiny data updates can be cheap.
+            - Setting this mode will call the `refresh` method of a MetaflowCard.
+            - It will result in the creation of a JSON object.
+
+    Parameters
+    ----------
+    mf_card : MetaflowCard
+        MetaflowCard object which will be used to render the card.
+    mode : str
+        Mode of rendering the card.
+    task : Task
+        Task object which will be passed to render the card.
+    data : dict
+        object created and passed down from `current.card._get_latest_data` method.
+        For more information on this object's schema have a look at `current.card._get_latest_data` method.
+    timeout_value : int
+        Timeout value for rendering the card.
+
+    Returns
+    -------
+    CardRenderInfo
+        - NamedTuple which will contain:
+            - `mode`: The mode of rendering the card.
+            - `is_implemented`: whether the function was implemented or not.
+            - `data` : output from rendering the card (Can be string/dict)
+            - `timed_out` : whether the function timed out or not.
+            - `timeout_stack_trace` : stack trace of the function if it timed out.
+    """
+
+    def _reload_token():
+        if "render_seq" not in data:
+            return "never"
+
+        if data["render_seq"] == "final":
+            # final data update should always trigger a card reload to show
+            # the final card, hence a different token for the final update
+            return "final"
+        elif mf_card.RELOAD_POLICY == mf_card.RELOAD_POLICY_ALWAYS:
+            return "render-seq-%s" % data["render_seq"]
+        elif mf_card.RELOAD_POLICY == mf_card.RELOAD_POLICY_NEVER:
+            return "never"
+        elif mf_card.RELOAD_POLICY == mf_card.RELOAD_POLICY_ONCHANGE:
+            return mf_card.reload_content_token(task, data)
+
+    def _add_token_html(html):
+        if html is None:
+            return None
+        return html.replace(mf_card.RELOAD_POLICY_TOKEN, _reload_token())
+
+    def _add_token_json(json_msg):
+        if json_msg is None:
+            return None
+        return {"reload_token": _reload_token(), "data": json_msg}
+
+    def _safe_call_function(func, *args, **kwargs):
+        """
+        returns (data, is_implemented)
+        """
+        try:
+            return func(*args, **kwargs), True
+        except NotImplementedError as e:
+            return None, False
+
+    def _call():
+        if mode == "render":
+            setattr(
+                mf_card.__class__,
+                "runtime_data",
+                property(fget=lambda _, data=data: data),
+            )
+            output = _add_token_html(mf_card.render(task))
+            return CardRenderInfo(
+                mode=mode,
+                is_implemented=True,
+                data=output,
+                timed_out=False,
+                timeout_stack_trace=None,
+            )
+
+        elif mode == "render_runtime":
+            # Since many cards created by metaflow users may not have implemented a
+            # `render_time` / `refresh` methods, it can result in an exception and thereby
+            # creation of error cards (especially for the `render_runtime` method). So instead
+            # we will catch the NotImplementedError and return None if users have not implemented it.
+            # If there any any other exception from the user code, it should be bubbled to the top level.
+            output, is_implemented = _safe_call_function(
+                mf_card.render_runtime, task, data
+            )
+            return CardRenderInfo(
+                mode=mode,
+                is_implemented=is_implemented,
+                data=_add_token_html(output),
+                timed_out=False,
+                timeout_stack_trace=None,
+            )
+
+        elif mode == "refresh":
+            output, is_implemented = _safe_call_function(mf_card.refresh, task, data)
+            return CardRenderInfo(
+                mode=mode,
+                is_implemented=is_implemented,
+                data=_add_token_json(output),
+                timed_out=False,
+                timeout_stack_trace=None,
+            )
+
+    render_info = None
     if timeout_value is None or timeout_value < 0:
-        rendered_info = mf_card.render(task)
+        return _call()
     else:
-        with timeout(timeout_value):
-            rendered_info = mf_card.render(task)
-    return rendered_info
+        try:
+            with timeout(timeout_value):
+                render_info = _call()
+        except TimeoutError:
+            stack_trace = traceback.format_exc()
+            return CardRenderInfo(
+                mode=mode,
+                is_implemented=True,
+                data=None,
+                timed_out=True,
+                timeout_stack_trace=stack_trace,
+            )
+        return render_info
 
 
 @card.command(help="create a HTML card")
@@ -414,29 +555,64 @@ def render_card(mf_card, task, timeout_value=None):
     is_flag=True,
     help="Upon failing to render a card, render a card holding the stack trace",
 )
+@click.option(
+    "--id",
+    default=None,
+    show_default=True,
+    type=str,
+    help="ID of the card",
+)
 @click.option(
     "--component-file",
     default=None,
     show_default=True,
     type=str,
-    help="JSON File with Pre-rendered components.(internal)",
+    help="JSON File with pre-rendered components. (internal)",
 )
 @click.option(
-    "--id",
+    "--mode",
+    default="render",
+    show_default=True,
+    type=click.Choice(["render", "render_runtime", "refresh"]),
+    help="Rendering mode. (internal)",
+)
+@click.option(
+    "--data-file",
     default=None,
     show_default=True,
     type=str,
-    help="ID of the card",
+    hidden=True,
+    help="JSON file containing data to be updated. (internal)",
+)
+@click.option(
+    "--card-uuid",
+    default=None,
+    show_default=True,
+    type=str,
+    hidden=True,
+    help="Card UUID. (internal)",
+)
+@click.option(
+    "--delete-input-files",
+    default=False,
+    is_flag=True,
+    show_default=True,
+    hidden=True,
+    help="Delete data-file and component-file after reading. (internal)",
 )
 @click.pass_context
 def create(
     ctx,
     pathspec,
+    mode=None,
     type=None,
     options=None,
     timeout=None,
     component_file=None,
+    data_file=None,
     render_error_card=False,
+    card_uuid=None,
+    delete_input_files=None,
     id=None,
 ):
     card_id = id
@@ -452,11 +628,26 @@ def create(
 
     graph_dict, _ = ctx.obj.graph.output_steps()
 
+    if card_uuid is None:
+        card_uuid = str(uuid.uuid4()).replace("-", "")
+
     # Components are rendered in a Step and added via `current.card.append` are added here.
     component_arr = []
     if component_file is not None:
         with open(component_file, "r") as f:
             component_arr = json.load(f)
+        # Component data used in card runtime is passed in as temporary files which can be deleted after use
+        if delete_input_files:
+            os.remove(component_file)
+
+    # Load data to be refreshed for runtime cards
+    data = {}
+    if data_file is not None:
+        with open(data_file, "r") as f:
+            data = json.load(f)
+        # data is passed in as temporary files which can be deleted after use
+        if delete_input_files:
+            os.remove(data_file)
 
     task = Task(full_pathspec)
     from metaflow.plugins import CARDS
@@ -498,23 +689,88 @@ def create(
             else:
                 raise IncorrectCardArgsException(type, options)
 
+        rendered_content = None
         if mf_card:
             try:
-                rendered_info = render_card(mf_card, task, timeout_value=timeout)
+                rendered_info = update_card(
+                    mf_card, mode, task, data, timeout_value=timeout
+                )
+                rendered_content = rendered_info.data
             except:
+                rendered_info = CardRenderInfo(
+                    mode=mode,
+                    is_implemented=True,
+                    data=None,
+                    timed_out=False,
+                    timeout_stack_trace=None,
+                )
                 if render_error_card:
                     error_stack_trace = str(UnrenderableCardException(type, options))
                 else:
                     raise UnrenderableCardException(type, options)
-        #
-
-    if error_stack_trace is not None:
-        rendered_info = error_card().render(task, stack_trace=error_stack_trace)
 
-    if rendered_info is None and render_error_card:
-        rendered_info = error_card().render(
-            task, stack_trace="No information rendered From card of type %s" % type
+    # In the entire card rendering process, there are a few cases we want to handle:
+    # - [mode == "render"]
+    #   1. Card is rendered successfully (We store it in the datastore as a HTML file)
+    #   2. Card is not rendered successfully and we have --save-error-card flag set to True
+    #      (We store it in the datastore as a HTML file with stack trace)
+    #   3. Card render timed-out and we have --save-error-card flag set to True
+    #      (We store it in the datastore as a HTML file with stack trace)
+    #   4. `render` returns nothing and we have --save-error-card flag set to True.
+    #       (We store it in the datastore as a HTML file with some message saying you returned nothing)
+    # - [mode == "render_runtime"]
+    #   1. Card is rendered successfully (We store it in the datastore as a HTML file)
+    #   2. `render_runtime` is not implemented but gets called and we have --save-error-card flag set to True.
+    #       (We store it in the datastore as a HTML file with some message saying the card should not be a runtime card if this method is not Implemented)
+    #   3. `render_runtime` is implemented and raises an exception and we have --save-error-card flag set to True.
+    #       (We store it in the datastore as a HTML file with stack trace)
+    #   4. `render_runtime` is implemented but returns nothing and we have --save-error-card flag set to True.
+    #       (We store it in the datastore as a HTML file with some message saying you returned nothing)
+    #   5. `render_runtime` is implemented but times out and we have --save-error-card flag set to True.
+    #       (We store it in the datastore as a HTML file with stack trace)
+    # - [mode == "refresh"]
+    #   1. Data update is created successfully (We store it in the datastore as a JSON file)
+    #   2. `refresh` is not implemented. (We do nothing. Don't store anything.)
+    #   3. `refresh` is implemented but it raises an exception. (We do nothing. Don't store anything.)
+    #   4. `refresh` is implemented but it times out. (We do nothing. Don't store anything.)
+
+    if error_stack_trace is not None and mode != "refresh":
+        rendered_content = error_card().render(task, stack_trace=error_stack_trace)
+
+    if (
+        rendered_info.is_implemented
+        and rendered_info.timed_out
+        and mode != "refresh"
+        and render_error_card
+    ):
+        timeout_stack_trace = (
+            "\nCard rendering timed out after %s seconds. "
+            "To increase the timeout duration for card rendering, please set the `timeout` parameter in the @card decorator. "
+            "\nStack Trace : \n%s"
+        ) % (timeout, rendered_info.timeout_stack_trace)
+        rendered_content = error_card().render(
+            task,
+            stack_trace=timeout_stack_trace,
+        )
+    elif (
+        rendered_info.is_implemented
+        and rendered_info.data is None
+        and render_error_card
+        and mode != "refresh"
+    ):
+        rendered_content = error_card().render(
+            task, stack_trace="No information rendered from card of type %s" % type
         )
+    elif (
+        not rendered_info.is_implemented
+        and render_error_card
+        and mode == "render_runtime"
+    ):
+        message = (
+            "Card of type %s is a runtime time card with no `render_runtime` implemented. "
+            "Please implement `render_runtime` method to allow rendering this card at runtime."
+        ) % type
+        rendered_content = error_card().render(task, stack_trace=message)
 
     # todo : should we save native type for error card or error type ?
     if type is not None and re.match(CARD_ID_PATTERN, type) is not None:
@@ -531,13 +787,21 @@ def create(
         )
         card_id = None
 
-    if rendered_info is not None:
-        card_info = card_datastore.save_card(save_type, rendered_info, card_id=card_id)
-        ctx.obj.echo(
-            "Card created with type: %s and hash: %s"
-            % (card_info.type, card_info.hash[:NUM_SHORT_HASH_CHARS]),
-            fg="green",
-        )
+    if rendered_content is not None:
+        if mode == "refresh":
+            card_datastore.save_data(
+                card_uuid, save_type, rendered_content, card_id=card_id
+            )
+            ctx.obj.echo("Data updated", fg="green")
+        else:
+            card_info = card_datastore.save_card(
+                card_uuid, save_type, rendered_content, card_id=card_id
+            )
+            ctx.obj.echo(
+                "Card created with type: %s and hash: %s"
+                % (card_info.type, card_info.hash[:NUM_SHORT_HASH_CHARS]),
+                fg="green",
+            )
 
 
 @card.command()
@@ -655,7 +919,6 @@ def list(
     as_json=False,
     file=None,
 ):
-
     card_id = id
     if pathspec is None:
         list_many_cards(
@@ -687,3 +950,125 @@ def list(
         show_list_as_json=as_json,
         file=file,
     )
+
+
+@card.command(help="Run local card viewer server")
+@click.option(
+    "--run-id",
+    default=None,
+    show_default=True,
+    type=str,
+    help="Run ID of the flow",
+)
+@click.option(
+    "--port",
+    default=8324,
+    show_default=True,
+    type=int,
+    help="Port on which Metaflow card viewer server will run",
+)
+@click.option(
+    "--namespace",
+    "user_namespace",
+    default=None,
+    show_default=True,
+    type=str,
+    help="Namespace of the flow",
+)
+@click.option(
+    "--poll-interval",
+    default=5,
+    show_default=True,
+    type=int,
+    help="Polling interval of the card viewer server.",
+)
+@click.option(
+    "--max-cards",
+    default=30,
+    show_default=True,
+    type=int,
+    help="Maximum number of cards to be shown at any time by the card viewer server",
+)
+@click.pass_context
+def server(ctx, run_id, port, user_namespace, poll_interval, max_cards):
+    from .card_server import create_card_server, CardServerOptions
+
+    user_namespace = resolve_identity() if user_namespace is None else user_namespace
+    run, follow_new_runs, _status_message = _get_run_object(
+        ctx.obj, run_id, user_namespace
+    )
+    if _status_message is not None:
+        ctx.obj.echo(_status_message, fg="red")
+    options = CardServerOptions(
+        flow_name=ctx.obj.flow.name,
+        run_object=run,
+        only_running=False,
+        follow_resumed=False,
+        flow_datastore=ctx.obj.flow_datastore,
+        max_cards=max_cards,
+        follow_new_runs=follow_new_runs,
+        poll_interval=poll_interval,
+    )
+    create_card_server(options, port, ctx.obj)
+
+
+def _get_run_from_cli_set_runid(obj, run_id):
+    # This run-id will be set from the command line args.
+    # So if we hit a MetaflowNotFound exception / Namespace mismatch then
+    # we should raise an exception
+    from metaflow import Run
+
+    flow_name = obj.flow.name
+    if len(run_id.split("/")) > 1:
+        raise CommandException(
+            "run_id should NOT be of the form: `<flowname>/<runid>`. Please provide only run-id"
+        )
+    try:
+        pathspec = "%s/%s" % (flow_name, run_id)
+        # Since we are looking at all namespaces,
+        # we will not
+        namespace(None)
+        return Run(pathspec)
+    except MetaflowNotFound:
+        raise CommandException("No run (%s) found for *%s*." % (run_id, flow_name))
+
+
+def _get_run_object(obj, run_id, user_namespace):
+    from metaflow import Flow
+
+    follow_new_runs = True
+    flow_name = obj.flow.name
+
+    if run_id is not None:
+        follow_new_runs = False
+        run = _get_run_from_cli_set_runid(obj, run_id)
+        obj.echo("Using run-id %s" % run.pathspec, fg="blue", bold=False)
+        return run, follow_new_runs, None
+
+    _msg = "Searching for runs in namespace: %s" % user_namespace
+    obj.echo(_msg, fg="blue", bold=False)
+
+    try:
+        namespace(user_namespace)
+        flow = Flow(pathspec=flow_name)
+        run = flow.latest_run
+    except MetaflowNotFound:
+        # When we have no runs found for the Flow, we need to ensure that
+        # if the `follow_new_runs` is set to True; If `follow_new_runs` is set to True then
+        # we don't raise the Exception and instead we return None and let the
+        # background Thread wait on the Retrieving the run object.
+        _status_msg = "No run found for *%s*." % flow_name
+        return None, follow_new_runs, _status_msg
+
+    except MetaflowNamespaceMismatch:
+        _status_msg = (
+            "No run found for *%s* in namespace *%s*. You can switch the namespace using --namespace"
+            % (
+                flow_name,
+                user_namespace,
+            )
+        )
+        return None, follow_new_runs, _status_msg
+
+    obj.echo("Using run-id %s" % run.pathspec, fg="blue", bold=False)
+    return run, follow_new_runs, None

metaflow/plugins/cards/card_client.py

@@ -2,10 +2,10 @@ from typing import Optional, Union, TYPE_CHECKING
 from metaflow.datastore import FlowDataStore
 from metaflow.metaflow_config import CARD_SUFFIX
 from .card_resolver import resolve_paths_from_task, resumed_info
-from .card_datastore import CardDatastore
+from .card_datastore import CardDatastore, CardNameSuffix
 from .exception import (
     UnresolvableDatastoreException,
-    IncorrectArguementException,
+    IncorrectArgumentException,
     IncorrectPathspecException,
 )
 import os
@@ -57,6 +57,15 @@ class Card:
         # Tempfile to open stuff in browser
         self._temp_file = None
 
+    def get_data(self) -> Optional[dict]:
+        # currently an internal method to retrieve a card's data.
+        data_paths = self._card_ds.extract_data_paths(
+            card_type=self.type, card_hash=self.hash, card_id=self._card_id
+        )
+        if len(data_paths) == 0:
+            return None
+        return self._card_ds.get_card_data(data_paths[0])
+
     def get(self) -> str:
         """
         Retrieves the HTML contents of the card from the
@@ -150,12 +159,12 @@ class CardContainer:
     ```
     """
 
-    def __init__(self, card_paths, card_ds, from_resumed=False, origin_pathspec=None):
+    def __init__(self, card_paths, card_ds, origin_pathspec=None):
         self._card_paths = card_paths
         self._card_ds = card_ds
         self._current = 0
         self._high = len(card_paths)
-        self.from_resumed = from_resumed
+        self.from_resumed = origin_pathspec is not None
         self.origin_pathspec = origin_pathspec
 
     def __len__(self):
@@ -172,7 +181,7 @@ class CardContainer:
         if index >= self._high:
             raise IndexError
         path = self._card_paths[index]
-        card_info = self._card_ds.card_info_from_path(path)
+        card_info = self._card_ds.info_from_path(path, suffix=CardNameSuffix.CARD)
         # todo : find card creation date and put it in client.
         return Card(
             self._card_ds,
@@ -250,8 +259,9 @@ def get_cards(
         task = Task(task_str)
     elif not isinstance(task, Task):
         # Exception that the task argument should be of form `Task` or `str`
-        raise IncorrectArguementException(_TYPE(task))
+        raise IncorrectArgumentException(_TYPE(task))
 
+    origin_taskpathspec = None
     if follow_resumed:
         origin_taskpathspec = resumed_info(task)
         if origin_taskpathspec:
@@ -263,7 +273,6 @@ def get_cards(
     return CardContainer(
         card_paths,
         card_ds,
-        from_resumed=origin_taskpathspec is not None,
         origin_pathspec=origin_taskpathspec,
     )