Render raw HTML as a Metaflow card.
pip install metaflow-card-htmlTo use the HTML card, you need to supply the type=html argument to the @card decorator. You can then set the html attribute of your Flow to an html string you want to render:
@card(type='html')
@step
def train(self):
...
...
self.html = some_html() # set some html to the self attributeIn these examples, we assume some_html is returning a HTML string, like this:
def some_html():
return "<html><body><h1 style='color: blue'>Hello World</h1></body></html>"However, you may want to use a different attribute name than html. To accomplish this, you can use the options parameter of the @card decorator. For example, if we wanted to store our HTML in an attribute named myhtml we would do the following:
@card(type='html',options={"attribute":"myhtml"}) # set the attribute name to myhtml
@step
def train(self):
...
...
self.myhtml = some_html() # set the html like beforeSome things to keep in mind about this card:
- This card is meant to render HTML passed as a string. If you pass a non-string value, this card will attempt to render it as a string instead.
- Failure to render a card will not result in an error in the flow.
You may want to implement your own card modules to customize your own workflows. This HTML card also serves as a great example of how to implement your own card modules. You can follow the steps below to accomplish this:
To get started create the following directory structure:
some_random_dir/ # the name of this dir doesn't matter
├ setup.py
├ metaflow_extensions/ # namespace package name
│ └ card_html/ # NO __init__.py file, rename this folder to card_yourcardname
│ └ plugins/ # NO __init__.py file
│ └ cards/ # NO __init__.py file
│ └ my_card_module/ # Name of card_module
│ └ __init__.py. # This is the __init__.py is required to recoginize `my_card_module` as a package
│ └ somerandomfile.py. # [Optional] some file as a part of the package.
.
If you are using GitHub, you can easily create this directory structure by using this template. Otherwise, you can copy the directory structure in the template and modify it as indicated below.
Note: Metaflow cards are distributed via namespace packages, under the namespace metaflow_extensions. You need not worry about the mechanics of namespace packages to distribute or publish your own card module! We recommend just following the directory structure indicated above.
After creating the necessary directory structure, you will need to modify the following files/directories:
setup.py: review and change the parameters passed tosetupas appropriate. Do not forget to add dependencies to other packages if they are required.- Change the name of folder
metaflow_extensions/card_*tometaflow_extensions/card_<yourcardname>. This is a suggestion to help keep the directory structure consistent with other cards - Change the name of the folder
metaflow_extensions/..../cards/htmltometaflow_extensions/.../cards/<yourcardname>
In __init__.py located in metaflow_extensions/.../cards/<yourcardname>, you must import or define your custom card module. Here is a minimal example:
from metaflow.cards import MetaflowCard
class BasicCard(MetaflowCard):
type = "basic_card"
def render(self, task): # this function returns the HTML to be rendered
return task.data.html # assumes you are saving an attribute named `html` in the task
CARDS = [BasicCard]Note that __init__.py requires a CARDS attribute which needs to be a list of objects inheriting MetaflowCard class.
What is shown above is only a minimal example. Recall that in the HTML card, you can specify the name of the attribute via the options parameter. We can implement this functionality as follows:
from metaflow.cards import MetaflowCard
class HTMLCard(MetaflowCard):
type = 'html'
def __init__(self, options={"attribute":"html"}, **kwargs):
self._attr_nm = options.get("attribute", "html")
def render(self, task):
if self._attr_nm in task:
return str(task[self._attr_nm].data) # retrieves the html from the task by accessing `task[self._attr_nm]`
CARDS = [HTMLCard]Now that you have finished creating your custom card, you can install it so that it is present in the python path. You can then test your card by passing the correct argument for type to @card as follows (no need to import anything):
@card(type='helloworld')
@step
def train(self):
...
...
self.html = some_html() # set some html to the self attributeWe recommend setting up automated tests in CI if possible. Take a look at tests/ and .github/workflows/ for an example. This is optional.
You are now ready to publish your card to pyipi. If you have are not familiar with how to do this, you can follow the steps in this tutorial. For a more in-depth discussion on python packaging, you can read this article.
Now its time to let people know about your card! You can make a PR to this README as well as letting us know on Twitter, tagging @MetaflowOSS.