577 lines
16 KiB
Python
577 lines
16 KiB
Python
# Copyright (c) Streamlit Inc. (2018-2022) Snowflake Inc. (2022)
|
|
#
|
|
# Licensed under the Apache License, Version 2.0 (the "License");
|
|
# you may not use this file except in compliance with the License.
|
|
# You may obtain a copy of the License at
|
|
#
|
|
# http://www.apache.org/licenses/LICENSE-2.0
|
|
#
|
|
# Unless required by applicable law or agreed to in writing, software
|
|
# distributed under the License is distributed on an "AS IS" BASIS,
|
|
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
|
# See the License for the specific language governing permissions and
|
|
# limitations under the License.
|
|
|
|
"""Allows us to create and absorb changes (aka Deltas) to elements."""
|
|
|
|
import ast
|
|
import contextlib
|
|
import inspect
|
|
import re
|
|
import sys
|
|
import types
|
|
from typing import TYPE_CHECKING, Any, cast
|
|
|
|
from typing_extensions import Final
|
|
|
|
import streamlit
|
|
from streamlit.logger import get_logger
|
|
from streamlit.proto.DocString_pb2 import DocString as DocStringProto
|
|
from streamlit.proto.DocString_pb2 import Member as MemberProto
|
|
from streamlit.runtime.metrics_util import gather_metrics
|
|
from streamlit.runtime.scriptrunner.script_runner import (
|
|
__file__ as SCRIPTRUNNER_FILENAME,
|
|
)
|
|
from streamlit.runtime.secrets import Secrets
|
|
from streamlit.string_util import is_mem_address_str
|
|
|
|
if TYPE_CHECKING:
|
|
from streamlit.delta_generator import DeltaGenerator
|
|
|
|
|
|
LOGGER: Final = get_logger(__name__)
|
|
|
|
|
|
CONFUSING_STREAMLIT_SIG_PREFIXES: Final = ("(element, ",)
|
|
|
|
|
|
class HelpMixin:
|
|
@gather_metrics("help")
|
|
def help(self, obj: Any = streamlit) -> "DeltaGenerator":
|
|
"""Display help and other information for a given object.
|
|
|
|
Depending on the type of object that is passed in, this displays the
|
|
object's name, type, value, signature, docstring, and member variables,
|
|
methods — as well as the values/docstring of members and methods.
|
|
|
|
Parameters
|
|
----------
|
|
obj : any
|
|
The object whose information should be displayed. If left
|
|
unspecified, this call will display help for Streamlit itself.
|
|
|
|
Example
|
|
-------
|
|
|
|
Don't remember how to initialize a dataframe? Try this:
|
|
|
|
>>> import streamlit as st
|
|
>>> import pandas
|
|
>>>
|
|
>>> st.help(pandas.DataFrame)
|
|
|
|
.. output::
|
|
https://doc-string.streamlit.app/
|
|
height: 700px
|
|
|
|
Want to quickly check what data type is output by a certain function?
|
|
Try:
|
|
|
|
>>> import streamlit as st
|
|
>>>
|
|
>>> x = my_poorly_documented_function()
|
|
>>> st.help(x)
|
|
|
|
Want to quickly inspect an object? No sweat:
|
|
|
|
>>> class Dog:
|
|
>>> '''A typical dog.'''
|
|
>>>
|
|
>>> def __init__(self, breed, color):
|
|
>>> self.breed = breed
|
|
>>> self.color = color
|
|
>>>
|
|
>>> def bark(self):
|
|
>>> return 'Woof!'
|
|
>>>
|
|
>>>
|
|
>>> fido = Dog('poodle', 'white')
|
|
>>>
|
|
>>> st.help(fido)
|
|
|
|
.. output::
|
|
https://doc-string1.streamlit.app/
|
|
height: 300px
|
|
|
|
And if you're using Magic, you can get help for functions, classes,
|
|
and modules without even typing ``st.help``:
|
|
|
|
>>> import streamlit as st
|
|
>>> import pandas
|
|
>>>
|
|
>>> # Get help for Pandas read_csv:
|
|
>>> pandas.read_csv
|
|
>>>
|
|
>>> # Get help for Streamlit itself:
|
|
>>> st
|
|
|
|
.. output::
|
|
https://doc-string2.streamlit.app/
|
|
height: 700px
|
|
"""
|
|
doc_string_proto = DocStringProto()
|
|
_marshall(doc_string_proto, obj)
|
|
return self.dg._enqueue("doc_string", doc_string_proto)
|
|
|
|
@property
|
|
def dg(self) -> "DeltaGenerator":
|
|
"""Get our DeltaGenerator."""
|
|
return cast("DeltaGenerator", self)
|
|
|
|
|
|
def _marshall(doc_string_proto: DocStringProto, obj: Any) -> None:
|
|
"""Construct a DocString object.
|
|
|
|
See DeltaGenerator.help for docs.
|
|
"""
|
|
var_name = _get_variable_name()
|
|
if var_name is not None:
|
|
doc_string_proto.name = var_name
|
|
|
|
obj_type = _get_type_as_str(obj)
|
|
doc_string_proto.type = obj_type
|
|
|
|
obj_docs = _get_docstring(obj)
|
|
if obj_docs is not None:
|
|
doc_string_proto.doc_string = obj_docs
|
|
|
|
obj_value = _get_value(obj, var_name)
|
|
if obj_value is not None:
|
|
doc_string_proto.value = obj_value
|
|
|
|
doc_string_proto.members.extend(_get_members(obj))
|
|
|
|
|
|
def _get_name(obj):
|
|
# Try to get the fully-qualified name of the object.
|
|
# For example:
|
|
# st.help(bar.Baz(123))
|
|
#
|
|
# The name is bar.Baz
|
|
name = getattr(obj, "__qualname__", None)
|
|
if name:
|
|
return name
|
|
|
|
# Try to get the name of the object.
|
|
# For example:
|
|
# st.help(bar.Baz(123))
|
|
#
|
|
# The name is Baz
|
|
return getattr(obj, "__name__", None)
|
|
|
|
|
|
def _get_module(obj):
|
|
return getattr(obj, "__module__", None)
|
|
|
|
|
|
def _get_signature(obj):
|
|
if not inspect.isclass(obj) and not callable(obj):
|
|
return None
|
|
|
|
sig = ""
|
|
|
|
# TODO: Can we replace below with this?
|
|
# with contextlib.suppress(ValueError):
|
|
# sig = str(inspect.signature(obj))
|
|
|
|
try:
|
|
sig = str(inspect.signature(obj))
|
|
except ValueError:
|
|
sig = "(...)"
|
|
except TypeError:
|
|
return None
|
|
|
|
is_delta_gen = False
|
|
with contextlib.suppress(AttributeError):
|
|
is_delta_gen = obj.__module__ == "streamlit.delta_generator"
|
|
# Functions such as numpy.minimum don't have a __module__ attribute,
|
|
# since we're only using it to check if its a DeltaGenerator, its ok
|
|
# to continue
|
|
|
|
if is_delta_gen:
|
|
for prefix in CONFUSING_STREAMLIT_SIG_PREFIXES:
|
|
if sig.startswith(prefix):
|
|
sig = sig.replace(prefix, "(")
|
|
break
|
|
|
|
return sig
|
|
|
|
|
|
def _get_docstring(obj):
|
|
doc_string = inspect.getdoc(obj)
|
|
|
|
# Sometimes an object has no docstring, but the object's type does.
|
|
# If that's the case here, use the type's docstring.
|
|
# For objects where type is "type" we do not print the docs (e.g. int).
|
|
# We also do not print the docs for functions and methods if the docstring is empty.
|
|
if doc_string is None:
|
|
obj_type = type(obj)
|
|
|
|
if (
|
|
obj_type is not type
|
|
and obj_type is not types.ModuleType
|
|
and not inspect.isfunction(obj)
|
|
and not inspect.ismethod(obj)
|
|
):
|
|
doc_string = inspect.getdoc(obj_type)
|
|
|
|
if doc_string:
|
|
return doc_string.strip()
|
|
|
|
return None
|
|
|
|
|
|
def _get_variable_name():
|
|
"""Try to get the name of the variable in the current line, as set by the user.
|
|
|
|
For example:
|
|
foo = bar.Baz(123)
|
|
st.help(foo)
|
|
|
|
The name is "foo"
|
|
"""
|
|
code = _get_current_line_of_code_as_str()
|
|
|
|
if code is None:
|
|
return None
|
|
|
|
return _get_variable_name_from_code_str(code)
|
|
|
|
|
|
def _get_variable_name_from_code_str(code):
|
|
tree = ast.parse(code)
|
|
|
|
# Example:
|
|
#
|
|
# tree = Module(
|
|
# body=[
|
|
# Expr(
|
|
# value=Call(
|
|
# args=[
|
|
# Name(id='the variable name')
|
|
# ],
|
|
# keywords=[
|
|
# ???
|
|
# ],
|
|
# )
|
|
# )
|
|
# ]
|
|
# )
|
|
|
|
# Check if this is an magic call (i.e. it's not st.help or st.write).
|
|
# If that's the case, just clean it up and return it.
|
|
if not _is_stcommand(tree, command_name="help") and not _is_stcommand(
|
|
tree, command_name="write"
|
|
):
|
|
# A common pattern is to add "," at the end of a magic command to make it print.
|
|
# This removes that final ",", so it looks nicer.
|
|
if code.endswith(","):
|
|
code = code[:-1]
|
|
|
|
return code
|
|
|
|
arg_node = _get_stcommand_arg(tree)
|
|
|
|
# If st.help() is called without an argument, return no variable name.
|
|
if not arg_node:
|
|
return None
|
|
|
|
# If walrus, get name.
|
|
# E.g. st.help(foo := 123) should give you "foo".
|
|
# (The hasattr is there to support Python 3.7)
|
|
elif hasattr(ast, "NamedExpr") and type(arg_node) is ast.NamedExpr:
|
|
# This next "if" will always be true, but need to add this for the type-checking test to
|
|
# pass.
|
|
if type(arg_node.target) is ast.Name:
|
|
return arg_node.target.id
|
|
|
|
# If constant, there's no variable name.
|
|
# E.g. st.help("foo") or st.help(123) should give you None.
|
|
elif type(arg_node) in (
|
|
ast.Constant,
|
|
# Python 3.7 support:
|
|
ast.Num,
|
|
ast.Str,
|
|
ast.Bytes,
|
|
ast.NameConstant,
|
|
ast.Ellipsis,
|
|
):
|
|
return None
|
|
|
|
# Otherwise, return whatever is inside st.help(<-- here -->)
|
|
|
|
# But, if multiline, only return the first line.
|
|
code_lines = code.split("\n")
|
|
is_multiline = len(code_lines) > 1
|
|
|
|
start_offset = arg_node.col_offset
|
|
|
|
if is_multiline:
|
|
first_lineno = arg_node.lineno - 1 # Lines are 1-indexed!
|
|
first_line = code_lines[first_lineno]
|
|
end_offset = None
|
|
|
|
else:
|
|
first_line = code_lines[0]
|
|
end_offset = getattr(arg_node, "end_col_offset", -1)
|
|
|
|
# Python 3.7 and below have a bug where offset in some cases is off by one.
|
|
# See https://github.com/python/cpython/commit/b619b097923155a7034c05c4018bf06af9f994d0
|
|
# By the way, Python 3.7 also displays this bug when arg_node is a generator
|
|
# expression, but in that case there are further complications, so we're leaving it out
|
|
# of here. See the unit test for this for more details.
|
|
if sys.version_info < (3, 8) and type(arg_node) is ast.ListComp:
|
|
start_offset -= 1
|
|
|
|
return first_line[start_offset:end_offset]
|
|
|
|
|
|
_NEWLINES = re.compile(r"[\n\r]+")
|
|
|
|
|
|
def _get_current_line_of_code_as_str():
|
|
scriptrunner_frame = _get_scriptrunner_frame()
|
|
|
|
if scriptrunner_frame is None:
|
|
# If there's no ScriptRunner frame, something weird is going on. This
|
|
# can happen when the script is executed with `python myscript.py`.
|
|
# Either way, let's bail out nicely just in case there's some valid
|
|
# edge case where this is OK.
|
|
return None
|
|
|
|
code_context = scriptrunner_frame.code_context
|
|
|
|
if not code_context:
|
|
# Sometimes a frame has no code_context. This can happen inside certain exec() calls, for
|
|
# example. If this happens, we can't determine the variable name. Just return.
|
|
# For the background on why exec() doesn't produce code_context, see
|
|
# https://stackoverflow.com/a/12072941
|
|
return None
|
|
|
|
code_as_string = "".join(code_context)
|
|
return re.sub(_NEWLINES, "", code_as_string.strip())
|
|
|
|
|
|
def _get_scriptrunner_frame():
|
|
prev_frame = None
|
|
scriptrunner_frame = None
|
|
|
|
# Look back in call stack to get the variable name passed into st.help().
|
|
# The frame *before* the ScriptRunner frame is the correct one.
|
|
# IMPORTANT: This will change if we refactor the code. But hopefully our tests will catch the
|
|
# issue and we'll fix it before it lands upstream!
|
|
for frame in inspect.stack():
|
|
# Check if this is running inside a funny "exec()" block that won't provide the info we
|
|
# need. If so, just quit.
|
|
if frame.code_context is None:
|
|
return None
|
|
|
|
if frame.filename == SCRIPTRUNNER_FILENAME:
|
|
scriptrunner_frame = prev_frame
|
|
break
|
|
|
|
prev_frame = frame
|
|
|
|
return scriptrunner_frame
|
|
|
|
|
|
def _is_stcommand(tree, command_name):
|
|
"""Checks whether the AST in tree is a call for command_name."""
|
|
root_node = tree.body[0].value
|
|
|
|
if not type(root_node) is ast.Call:
|
|
return False
|
|
|
|
return (
|
|
# st call called without module. E.g. "help()"
|
|
getattr(root_node.func, "id", None) == command_name
|
|
or
|
|
# st call called with module. E.g. "foo.help()" (where usually "foo" is "st")
|
|
getattr(root_node.func, "attr", None) == command_name
|
|
)
|
|
|
|
|
|
def _get_stcommand_arg(tree):
|
|
"""Gets the argument node for the st command in tree (AST)."""
|
|
|
|
root_node = tree.body[0].value
|
|
|
|
if root_node.args:
|
|
return root_node.args[0]
|
|
|
|
return None
|
|
|
|
|
|
def _get_type_as_str(obj):
|
|
if inspect.isclass(obj):
|
|
return "class"
|
|
|
|
return str(type(obj).__name__)
|
|
|
|
|
|
def _get_first_line(text):
|
|
if not text:
|
|
return ""
|
|
|
|
left, _, _ = text.partition("\n")
|
|
return left
|
|
|
|
|
|
def _get_weight(value):
|
|
if inspect.ismodule(value):
|
|
return 3
|
|
if inspect.isclass(value):
|
|
return 2
|
|
if callable(value):
|
|
return 1
|
|
return 0
|
|
|
|
|
|
def _get_value(obj, var_name):
|
|
obj_value = _get_human_readable_value(obj)
|
|
|
|
if obj_value is not None:
|
|
return obj_value
|
|
|
|
# If there's no human-readable value, it's some complex object.
|
|
# So let's provide other info about it.
|
|
name = _get_name(obj)
|
|
|
|
if name:
|
|
name_obj = obj
|
|
else:
|
|
# If the object itself doesn't have a name, then it's probably an instance
|
|
# of some class Foo. So let's show info about Foo in the value slot.
|
|
name_obj = type(obj)
|
|
name = _get_name(name_obj)
|
|
|
|
module = _get_module(name_obj)
|
|
sig = _get_signature(name_obj) or ""
|
|
|
|
if name:
|
|
if module:
|
|
obj_value = f"{module}.{name}{sig}"
|
|
else:
|
|
obj_value = f"{name}{sig}"
|
|
|
|
if obj_value == var_name:
|
|
# No need to repeat the same info.
|
|
# For example: st.help(re) shouldn't show "re module re", just "re module".
|
|
obj_value = None
|
|
|
|
return obj_value
|
|
|
|
|
|
def _get_human_readable_value(value):
|
|
if isinstance(value, Secrets):
|
|
# Don't want to read secrets.toml because that will show a warning if there's no
|
|
# secrets.toml file.
|
|
return None
|
|
|
|
if inspect.isclass(value) or inspect.ismodule(value) or callable(value):
|
|
return None
|
|
|
|
value_str = repr(value)
|
|
|
|
if isinstance(value, str):
|
|
# Special-case strings as human-readable because they're allowed to look like
|
|
# "<foo blarg at 0x15ee6f9a0>".
|
|
return _shorten(value_str)
|
|
|
|
if is_mem_address_str(value_str):
|
|
# If value_str looks like "<foo blarg at 0x15ee6f9a0>" it's not human readable.
|
|
return None
|
|
|
|
return _shorten(value_str)
|
|
|
|
|
|
def _shorten(s, length=300):
|
|
s = s.strip()
|
|
return s[:length] + "..." if len(s) > length else s
|
|
|
|
|
|
def _is_computed_property(obj, attr_name):
|
|
obj_class = getattr(obj, "__class__", None)
|
|
|
|
if not obj_class:
|
|
return False
|
|
|
|
# Go through superclasses in order of inheritance (mro) to see if any of them have an
|
|
# attribute called attr_name. If so, check if it's a @property.
|
|
for parent_class in inspect.getmro(obj_class):
|
|
class_attr = getattr(parent_class, attr_name, None)
|
|
|
|
if class_attr is None:
|
|
continue
|
|
|
|
# If is property, return it.
|
|
if isinstance(class_attr, property) or inspect.isgetsetdescriptor(class_attr):
|
|
return True
|
|
|
|
return False
|
|
|
|
|
|
def _get_members(obj):
|
|
members_for_sorting = []
|
|
|
|
for attr_name in dir(obj):
|
|
if attr_name.startswith("_"):
|
|
continue
|
|
|
|
is_computed_value = _is_computed_property(obj, attr_name)
|
|
|
|
if is_computed_value:
|
|
parent_attr = getattr(obj.__class__, attr_name)
|
|
|
|
member_type = "property"
|
|
|
|
weight = 0
|
|
member_docs = _get_docstring(parent_attr)
|
|
member_value = None
|
|
else:
|
|
attr_value = getattr(obj, attr_name)
|
|
weight = _get_weight(attr_value)
|
|
|
|
human_readable_value = _get_human_readable_value(attr_value)
|
|
|
|
member_type = _get_type_as_str(attr_value)
|
|
|
|
if human_readable_value is None:
|
|
member_docs = _get_docstring(attr_value)
|
|
member_value = None
|
|
else:
|
|
member_docs = None
|
|
member_value = human_readable_value
|
|
|
|
if member_type == "module":
|
|
# Don't pollute the output with all imported modules.
|
|
continue
|
|
|
|
member = MemberProto()
|
|
member.name = attr_name
|
|
member.type = member_type
|
|
|
|
if member_docs is not None:
|
|
member.doc_string = _get_first_line(member_docs)
|
|
|
|
if member_value is not None:
|
|
member.value = member_value
|
|
|
|
members_for_sorting.append((weight, member))
|
|
|
|
if members_for_sorting:
|
|
sorted_members = sorted(members_for_sorting, key=lambda x: (x[0], x[1].name))
|
|
return [m for _, m in sorted_members]
|
|
|
|
return []
|