Dashborg Documentation / References / Python SDK Reference

Python SDK Reference

Install:

pip install dashborg-python-sdk

Import:

import dashborg

dashborg

  • async connect_client(config: dashborg.Config) -> dashborg.Client

dashborg.Client

  • is_connected() -> bool
  • global_fs_client() -> dashborg.FSClient
  • app_client() -> dashborg.AppClient
  • async shutdown(exit_err=None)
  • async wait_for_shutdown()

dashborg.FSClient

  • async set_json_path(path: str, data, fileopts: dashborg.FileOpts)
  • async set_static_path(path: str, fileopts: dashborg.FileOpts = None, *, strval: str = None, bytesval: bytes = None, stream=None, file_name: str = None, watch: bool = False)
  • async link_runtime(path: str, runtime, fileopts: FileOpts=None)
  • async link_app_runtime(path: str, runtime, fileopts: FileOpts=None)
  • async make_path_url(path: str, jwt_opts: dict = None, no_jwt: bool = False)
  • async file_info(path: str)
  • async dir_info(path: str, role_list: list = ["*"], show_hidden: bool = False, recursive: bool = False)
  • async remove_path(path: str)
  • async set_raw_path(path: str, fileopts: dashborg.FileOpts, stream=None, runtime=None) – for low-level access. the other FSClient functions all call set_raw_path.

dashborg.AppClient

  • new_app(app_name: str)
  • new_app_from_config(app_config: dict)
  • async load_app(app_name: str, create: bool = False)
  • async write_app(app: dashborg.App, connect: bool = False)
  • make_app_url(app_name: str, jwt_opts: dict = None, no_jwt: bool = None)
  • async remove_app(app_name: str)

dashborg.LinkRuntime

  • handler(handler_name: str, handlerfn: typing.Callable, opts: HandlerOpts = None, pure_handler: bool = None, hidden: bool = None, display: str = None)

dashborg.AppRuntime

  • handler(handler_name: str, handlerfn: typing.Callable, opts: HandlerOpts = None, pure_handler: bool = None, hidden: bool = None, display: str = None)
  • html_handler(handlerfn: typing.Callable, **kwargs)
  • init_handler(handlerfn: typing.Callabke, **kwargs)
  • page_handler(page_name: str, handlerfn: typing.Callable)

dashborg.App

  • set_init_required(init_required: bool)

  • set_pages_enabled(enabled: bool)

  • set_allowed_roles(*roles: str)

  • set_app_title(title: str)

  • set_app_visibility(vis_type: str, vis_order: float = 0.0)

  • set_html(*, html: str = None, file_name: str = None, ext_path: str = None, runtime=False, stream=None, watch: bool = False)

  • app_fs_client() -> FSClient

  • get_app_config() -> dict

  • get_app_path() -> str

  • get_html_path() -> str

  • has_external_runtime() -> bool

  • get_runtime_path() -> str

dashborg.BlobReturn

  • init(mimetype: str, stream)

dashborg.FileOpts

  • init(filetype: str = None, sha256: str = None, size: int = None, mimetype: str = None, allowedroles: list = [“user”], editroles: list = None, display: str = None, metadata_json: str = None, metadata=None, description: str = None, mkdirs: bool = False, hidden: bool = False, appconfig: str = None)

dashborg.AppRequest

PanelRequest Field Description
app_name name of the app this request is from
req_id a unique id identifying this request
request_type “panel” or “data” depending on the type of handler
path the path for this handler
app_state value of “$.state” in panel
data arguments passed to this handler
data_json raw JSON passed to this handler
json_opts override default json serialization options
All data passed between the Dashborg service and your handlers is serialized and deserialized from JSON using the standard python json package. When decoding, values will be standard Python types.
PanelRequest Method Async App Runtime Pure Handler Description
set_data(path: str, data) * set panel data
invalidate_data(path: str) * force panel to update data (path is a regular expression). use req.invalidate_data(".*") to force a refresh of all data
nav_to_page(page_name: str, params=None) * Navigate the App to a new page with parameters. Can only be used with apps with pages_enabled set.
set_html_page(html_page: str) * Change the App’s HTML page (less common than nav_to_page)
get_page_name() * * Returns the page the app was on that generated this request

set_data

req.set_data(self, path, data, *, serialize=None, jsondumps=None, raw_json=None, jsondumpskwargs=None)

Used by panel handlers to return data to the UI. See serialization notes for how data is converted to JSON.

Returns: None

Arguments:

  • path - The data path to set. Usually starts with “$” or “$state”.
  • data - Data to set. See serialization notes.
  • serialize - To override the “serialize” function. Defaults to req.opts[“serialize”] which defaults to dashborg.serialize. Pass None to skip pre-serialization. The serialize function converts a non-JSON compatible type into a compatible type (e.g. turns a custom class to a dict or str).
  • jsondumps - To override the function to turn serialized data into json. Defaults to req.opts[“jsondumps”] which defaults to json.dumps.
  • jsondumpskwargs - If set, these arguments will be passed as **kwargs to json.dumps. Defaults to req.opts[“jsondumpskwargs”] which defaults to {}
  • raw_json - If set, data will be ignored. No serialization will be performed, and raw_json will be sent. Must be a properly formatted JSON string. Useful if you want to manually produce custom JSON.

Examples

   def handler_fn(req):
       req.set_data("$.data.x", 55)
       req.set_data("$.data.color", "blue")
       req.set_data("$.data.point", [-5, 25])
       req.set_data("$.data.tags", {"host": "localhost", "port": 80, "secure": True})
       req.set_data("$.data.myclass", MyClass(), serializer=my_serializer)
       req.set_data("$.data.custom_arr", None, raw_json="[1,2,3]")

Serialization Notes

Dashborg will recursively call the serialize function on any data passed to set_data or returned from a data handler. This helps to convert non-JSON native types to JSON for common cases.

The default dashborg.dbu.serialize() handles these cases automatically:

  • dict, list, str, int, float, boolean, and None as is to their standard JSON counterparts (note that bytes is not handled)
  • uuid.UUID - as a string str(uuid)
  • datetime.datetime - as unix timestamp in milliseconds int(round(dt.timestamp()*1000)) - for use with <d-dateformat>
  • datetime.date - as a string str(dt)
  • dataclasses using asdict()
  • calling the to_dict() method on any object if present
  • __iter__ as an array (note: bytes and str are handled above and will not use this case)
  • __dict__ or __slots__ gets converted to dict. Keys starting with “_” will be skipped.
  • _asdict, _ast for tuples

To customize serialization of a class, the easiest way is to add a to_dict method directly to the class. For classes where you do not control the source code, you can override the serialization function by:

  • pass a custom serializer to set_data using the serialize kwarg (see below)
  • set req.opts["serializer"] to a custom function (see below). This will override the serialization for the entire request (all set_data calls). Note: this will work to override the serialization for data handler return values.
  • Note: you can set serializer=None to bypass all custom serialization.
def my_serialize(obj):
    if isinstance(obj, MyClass):
       return {"special": True}  # SPECIAL CODE HERE
    if callable(obj):
       return None
    return dashborg.serialize(obj)
    
# later...

req.opts["serialize"] = my_serialize
# or
req.set_data("$.myclass", MyClass(), serialize=my_serialize)


dashborg.Config

Config Field Env Var Default Description
acc_id DASHBORG_ACCID account id, if blank a new account id will be generated if no keyfile is found, otherwise must match the account id in your key file
anon_acc set to True to allow the creation of a new anonymous account
zone_name DASHBORG_ZONE “default”
proc_name DASHBORG_PROCNAME sys.argv[0]
proc_ikey DASHBORG_PROCIKEY
proc_tags dictionary of strings
key_file_name DASHBORG_KEYFILE “dashborg-client.key” private key file
cert_file_name DASHBORG_CERTFILE “dashborg-client.crt” public key certificate file
auto_keygen set to True to allow dashborg to auto generate public/private key files if they are not found
verbose DASHBORG_VERBOSE False set to True for extra debug logging
grpc_host DASHBORG_GRPCHOST grpc.api.dashborg.net to override Dashborg gRPC host name
grpc_port DASHBORG_GRPCPORT 7632 to override Dashborg gRPC service port
use_logger False if True write logs/errors to python logger(“dashborg”) interface instead of stdout/print
jwt_opts {“valid_for_sec”: 24*60*60,
“role”: “user”,
“user_id”: “jwt-user”}
Used to customize the JWT tokens in links generated by your program. Maxium valid time is 24-hours.
no_jwt False set to True to disable printing of JWT tokens in links
json_opts {“serializefn”: dashborg.dbu.serialize,
“jsondumps”: json.dumps,
“jsondumpskwargs”: None}
Used to override default json serialization. serializefn, jsondumps, and jsodumpskwargs.

Common Config Settings

For anonymous accounts, and quick start use:

  config = dashborg.Config(anon_acc=True, auto_keygen=True)

For registered accounts where you are controlling the keys use:

  config = dashborg.Config(acc_id="YOUR ACC ID", key_file_name="KEY-PATH", cert_file_name="CERT-PATH")

For registered accounts where you want Dashborg to create new keys for your account. Note that you’ll have to register the public key fingerprint with your account (on accounts.dashborg.net) after it is generated. If you would like the keys generated at a specific path, also specify key_file_name and cert_file_name.

  config = dashborg.Config(acc_id="YOUR ACC ID", auto_keygen=True)