def write(self, *args, **kwargs): """Write arguments to the app. This is the Swiss Army knife of Streamlit commands: it does different things depending on what you throw at it. Unlike other Streamlit commands, write() has some unique properties: 1. You can pass in multiple arguments, all of which will be written. 2. Its behavior depends on the input types as follows. 3. It returns None, so it's "slot" in the App cannot be reused. Parameters ---------- *args : any One or many objects to print to the App. Arguments are handled as follows: - write(string) : Prints the formatted Markdown string, with support for LaTeX expression and emoji shortcodes. See docs for st.markdown for more. - write(data_frame) : Displays the DataFrame as a table. - write(error) : Prints an exception specially. - write(func) : Displays information about a function. - write(module) : Displays information about the module. - write(dict) : Displays dict in an interactive widget. - write(obj) : The default is to print str(obj). - write(mpl_fig) : Displays a Matplotlib figure. - write(altair) : Displays an Altair chart. - write(keras) : Displays a Keras model. - write(graphviz) : Displays a Graphviz graph. - write(plotly_fig) : Displays a Plotly figure. - write(bokeh_fig) : Displays a Bokeh figure. - write(sympy_expr) : Prints SymPy expression using LaTeX. unsafe_allow_html : bool This is a keyword-only argument that defaults to False. By default, any HTML tags found in strings will be escaped and therefore treated as pure text. This behavior may be turned off by setting this argument to True. That said, *we strongly advise* against it*. It is hard to write secure HTML, so by using this argument you may be compromising your users' security. For more information, see: https://github.com/streamlit/streamlit/issues/152 **Also note that `unsafe_allow_html` is a temporary measure and may be removed from Streamlit at any time.** If you decide to turn on HTML anyway, we ask you to please tell us your exact use case here: https://discuss.streamlit.io/t/96 . This will help us come up with safe APIs that allow you to do what you want. Example ------- Its basic use case is to draw Markdown-formatted text, whenever the input is a string: >>> write('Hello, *World!* :sunglasses:') .. output:: https://static.streamlit.io/0.50.2-ZWk9/index.html?id=Pn5sjhgNs4a8ZbiUoSTRxE height: 50px As mentioned earlier, `st.write()` also accepts other data formats, such as numbers, data frames, styled data frames, and assorted objects: >>> st.write(1234) >>> st.write(pd.DataFrame({ ... 'first column': [1, 2, 3, 4], ... 'second column': [10, 20, 30, 40], ... })) .. output:: https://static.streamlit.io/0.25.0-2JkNY/index.html?id=FCp9AMJHwHRsWSiqMgUZGD height: 250px Finally, you can pass in multiple arguments to do things like: >>> st.write('1 + 1 = ', 2) >>> st.write('Below is a DataFrame:', data_frame, 'Above is a dataframe.') .. output:: https://static.streamlit.io/0.25.0-2JkNY/index.html?id=DHkcU72sxYcGarkFbf4kK1 height: 300px Oh, one more thing: `st.write` accepts chart objects too! For example: >>> import pandas as pd >>> import numpy as np >>> import altair as alt >>> >>> df = pd.DataFrame( ... np.random.randn(200, 3), ... columns=['a', 'b', 'c']) ... >>> c = alt.Chart(df).mark_circle().encode( ... x='a', y='b', size='c', color='c', tooltip=['a', 'b', 'c']) >>> >>> st.write(c) .. output:: https://static.streamlit.io/0.25.0-2JkNY/index.html?id=8jmmXR8iKoZGV4kXaKGYV5 height: 200px """ string_buffer = [] # type: List[str] unsafe_allow_html = kwargs.get("unsafe_allow_html", False) # This bans some valid cases like: e = st.empty(); e.write("a", "b"). # BUT: 1) such cases are rare, 2) this rule is easy to understand, # and 3) this rule should be removed once we have st.container() if not self.dg._is_top_level and len(args) > 1: raise StreamlitAPIException( "Cannot replace a single element with multiple elements.\n\n" "The `write()` method only supports multiple elements when " "inserting elements rather than replacing. That is, only " "when called as `st.write()` or `st.sidebar.write()`.") def flush_buffer(): if string_buffer: self.dg.markdown( " ".join(string_buffer), unsafe_allow_html=unsafe_allow_html, ) string_buffer[:] = [] for arg in args: # Order matters! if isinstance(arg, str): string_buffer.append(arg) elif type_util.is_dataframe_like(arg): flush_buffer() if len(np.shape(arg)) > 2: self.dg.text(arg) else: self.dg.dataframe(arg) elif isinstance(arg, Exception): flush_buffer() self.dg.exception(arg) elif isinstance(arg, HELP_TYPES): flush_buffer() self.dg.help(arg) elif type_util.is_altair_chart(arg): flush_buffer() self.dg.altair_chart(arg) elif type_util.is_type(arg, "matplotlib.figure.Figure"): flush_buffer() self.dg.pyplot(arg) elif type_util.is_plotly_chart(arg): flush_buffer() self.dg.plotly_chart(arg) elif type_util.is_type(arg, "bokeh.plotting.figure.Figure"): flush_buffer() self.dg.bokeh_chart(arg) elif type_util.is_graphviz_chart(arg): flush_buffer() self.dg.graphviz_chart(arg) elif type_util.is_sympy_expession(arg): flush_buffer() self.dg.latex(arg) elif type_util.is_keras_model(arg): from tensorflow.python.keras.utils import vis_utils flush_buffer() dot = vis_utils.model_to_dot(arg) self.dg.graphviz_chart(dot.to_string()) elif isinstance(arg, (dict, list)): flush_buffer() self.dg.json(arg) elif type_util.is_namedtuple(arg): flush_buffer() self.dg.json(json.dumps(arg._asdict())) elif type_util.is_pydeck(arg): flush_buffer() self.dg.pydeck_chart(arg) else: string_buffer.append("`%s`" % str(arg).replace("`", "\\`")) flush_buffer()
def create_instance( self, *args, default: Any = None, key: Optional[str] = None, **kwargs, ) -> Any: """Create a new instance of the component. Parameters ---------- *args Must be empty; all args must be named. (This parameter exists to enforce correct use of the function.) default: any or None The default return value for the component. This is returned when the component's frontend hasn't yet specified a value with `setComponentValue`. key: str or None If not None, this is the user key we use to generate the component's "widget ID". **kwargs Keyword args to pass to the component. Returns ------- any or None The component's widget value. """ if len(args) > 0: raise MarshallComponentException( f"Argument '{args[0]}' needs a label") try: import pyarrow from streamlit.elements import arrow_table except ImportError: import sys if sys.version_info >= (3, 9): raise StreamlitAPIException( """To use Custom Components in Streamlit, you need to install PyArrow. Unfortunately, PyArrow does not yet support Python 3.9. You can either switch to Python 3.8 with an environment manager like PyEnv, or stay on 3.9 by [installing Streamlit with conda](https://discuss.streamlit.io/t/note-installation-issues-with-python-3-9-and-streamlit/6946): `conda install -c conda-forge streamlit` """) else: raise StreamlitAPIException( """To use Custom Components in Streamlit, you need to install PyArrow. To do so locally: `pip install pyarrow` And if you're using Streamlit Sharing, add "pyarrow" to your requirements.txt.""" ) # In addition to the custom kwargs passed to the component, we also # send the special 'default' and 'key' params to the component # frontend. all_args = dict(kwargs, **{"default": default, "key": key}) json_args = {} special_args = [] for arg_name, arg_val in all_args.items(): if type_util.is_bytes_like(arg_val): bytes_arg = SpecialArg() bytes_arg.key = arg_name bytes_arg.bytes = to_bytes(arg_val) special_args.append(bytes_arg) elif type_util.is_dataframe_like(arg_val): dataframe_arg = SpecialArg() dataframe_arg.key = arg_name arrow_table.marshall(dataframe_arg.arrow_dataframe.data, arg_val) special_args.append(dataframe_arg) else: json_args[arg_name] = arg_val try: serialized_json_args = json.dumps(json_args) except BaseException as e: raise MarshallComponentException( "Could not convert component args to JSON", e) def marshall_component(element: Element) -> Union[Any, Type[NoValue]]: element.component_instance.component_name = self.name if self.url is not None: element.component_instance.url = self.url # Normally, a widget's element_hash (which determines # its identity across multiple runs of an app) is computed # by hashing the entirety of its protobuf. This means that, # if any of the arguments to the widget are changed, Streamlit # considers it a new widget instance and it loses its previous # state. # # However! If a *component* has a `key` argument, then the # component's hash identity is determined by entirely by # `component_name + url + key`. This means that, when `key` # exists, the component will maintain its identity even when its # other arguments change, and the component's iframe won't be # remounted on the frontend. # # So: if `key` is None, we marshall the element's arguments # *before* computing its widget_ui_value (which creates its hash). # If `key` is not None, we marshall the arguments *after*. def marshall_element_args(): element.component_instance.json_args = serialized_json_args element.component_instance.special_args.extend(special_args) if key is None: marshall_element_args() widget_value = register_widget( element_type="component_instance", element_proto=element.component_instance, user_key=key, widget_func_name=self.name, ) if key is not None: marshall_element_args() if widget_value is None: widget_value = default elif isinstance(widget_value, ArrowTableProto): widget_value = arrow_table.arrow_proto_to_dataframe( widget_value) # widget_value will be either None or whatever the component's most # recent setWidgetValue value is. We coerce None -> NoValue, # because that's what DeltaGenerator._enqueue expects. return widget_value if widget_value is not None else NoValue # We currently only support writing to st._main, but this will change # when we settle on an improved API in a post-layout world. element = Element() return_value = marshall_component(element) result = streamlit._main._enqueue("component_instance", element.component_instance, return_value) return result
def create_instance( self, *args, default: Any = None, key: Optional[str] = None, **kwargs, ) -> Any: """Create a new instance of the component. Parameters ---------- *args Must be empty; all args must be named. (This parameter exists to enforce correct use of the function.) default: any or None The default return value for the component. This is returned when the component's frontend hasn't yet specified a value with `setComponentValue`. key: str or None If not None, this is the user key we use to generate the component's "widget ID". **kwargs Keyword args to pass to the component. Returns ------- any or None The component's widget value. """ if len(args) > 0: raise MarshallComponentException(f"Argument '{args[0]}' needs a label") json_args = {} special_args = [] for arg_name, arg_val in kwargs.items(): if type_util.is_bytes_like(arg_val): bytes_arg = SpecialArg() bytes_arg.key = arg_name bytes_arg.bytes = to_bytes(arg_val) special_args.append(bytes_arg) elif type_util.is_dataframe_like(arg_val): dataframe_arg = SpecialArg() dataframe_arg.key = arg_name arrow_table.marshall(dataframe_arg.arrow_dataframe.data, arg_val) special_args.append(dataframe_arg) else: json_args[arg_name] = arg_val try: serialized_json_args = json.dumps(json_args) except BaseException as e: raise MarshallComponentException( "Could not convert component args to JSON", e ) def marshall_component(element: Element) -> Union[Any, Type[NoValue]]: element.component_instance.component_name = self.name if self.url is not None: element.component_instance.url = self.url # Normally, a widget's element_hash (which determines # its identity across multiple runs of an app) is computed # by hashing the entirety of its protobuf. This means that, # if any of the arguments to the widget are changed, Streamlit # considers it a new widget instance and it loses its previous # state. # # However! If a *component* has a `key` argument, then the # component's hash identity is determined by entirely by # `component_name + url + key`. This means that, when `key` # exists, the component will maintain its identity even when its # other arguments change, and the component's iframe won't be # remounted on the frontend. # # So: if `key` is None, we marshall the element's arguments # *before* computing its widget_ui_value (which creates its hash). # If `key` is not None, we marshall the arguments *after*. def marshall_element_args(): element.component_instance.json_args = serialized_json_args element.component_instance.special_args.extend(special_args) if key is None: marshall_element_args() widget_value = _get_widget_ui_value( element_type="component_instance", element_proto=element.component_instance, user_key=key, widget_func_name=self.name, ) if key is not None: marshall_element_args() if widget_value is None: widget_value = default elif isinstance(widget_value, ArrowTableProto): widget_value = arrow_table.arrow_proto_to_dataframe(widget_value) # widget_value will be either None or whatever the component's most # recent setWidgetValue value is. We coerce None -> NoValue, # because that's what DeltaGenerator._enqueue expects. return widget_value if widget_value is not None else NoValue # We currently only support writing to st._main, but this will change # when we settle on an improved API in a post-layout world. element = Element() return_value = marshall_component(element) result = streamlit._main._enqueue( "component_instance", element.component_instance, return_value ) return result