SPy Add-ons

seeq.spy.addons.install(tool: DataFrame | Series | dict | list, *, include_workbook_parameters: bool = True, update_tool: bool = False, update_permissions: bool = False, in_development: bool = False, errors: str | None = None, quiet: bool | None = None, status: Status | None = None, session: Session | None = None) → DataFrame

Installs or updates Add-on tool(s) in Seeq Workbench. Installing Add-on tools for other users or groups requires administrator access. Installing Add-ons for personal use of non-admin users requires the argument in_development=True.

Parameters:

tool ({dict, list, pd.DataFrame, pd.Series}) –

Property	Description
Name	Required. The name of the Add-on tool (shown in green text in the Add-on Tool card).
Description	Required. The description of the Add-on tool (shown in black text underneath the Name in the tool card). Long descriptions will wrap to the next line and increase the height of the Add-on Tool button.
Target URL	Required.The URL that the Add-on will open. This can be any website but most commonly a Seeq Data Lab Notebook in Add-on Mode. In order to get the Target URL for a Seeq Data Lab Notebook, open the desired Notebook and copy the URL. In normal mode, the URL contains “/notebooks/” right after the project ID. If you want the notebook to be opened in Add-on Mode, replace “/notebooks/” for “/addon/” in the URL. For example: https://my.seeq.com/data-lab/<id>/addon/TEST.ipynb
Icon	Optional. Name of the fontawesome icon class to be displayed on the tool card. Defaults to “fa fa-minus”. Potential Font Awesome icons can be found at the website https://fontawesome.com/v4.7.0/icons/ and take the form of “fa fa-<icon>” Be sure to include the standalone “fa” in addition to the icon name.
Launch Location	Optional. Sets the display location characteristics. Defaults to “toolsPane”. Options are one of the following: - “toolsPane” - display in Add-on Tools Pane. - “homescreen” - display in Add-ons homescreen.
Link Type	Optional. Sets the display characteristics. Defaults to “window”. Options are one of the following: ”window” - display in a new window. After the windows is opened, the user is responsible for subsequent managing of window placement. ”tab” - display in a new tab of the current browser window. ”none” - make a GET request to the URL but do not open a window or tab. Although supported, its use is expected to be rare. It should generally be avoided because it gives the tool card a non-standard button-like behavior.
Window Details	Optional if Link Type is “window”. Sets display characteristics used when Link Type is set to “window”. Options are available at https://developer.mozilla.org/en-US/docs/Web/API/Window/open#Window_features. For example: “toolbar=0,height=600,width=600”
Sort Key	Optional. A string, typically a single character letter. Determines the order in which the Add-on Tools are displayed in the tool panel. The Add-on Tools panel sorts the list of add-ons by this key to determine ordering.
Reuse Window	Optional. Defaults to False. If True, sets focus to existing window if already opened. Otherwise, open a new window. If False, a new window is opened each time the tool card is clicked. This parameter is only valid when Link Type is set to “window”.
Groups	Optional. List of the Seeq groups that have permission to access the Add-on tool. If the Add-on Tool Target URL is a Data Lab Notebook, then any permissions set on the Add-on Tool will also be added to the target Data Lab Project as users are required to have at least write permissions on the Data Lab Project to run the Notebook. Passing an empty list will remove permissions to the tool for all groups (without modifying permissions to the Target URL). If the tool exists, set update_permissions to True to overwrite the previous Groups permissions. If the tool exists and update_permissions is False, then permissions will not update.
Users	Optional. List of the Seeq users by username that have permission to access the Add-on tool. To figure out a username, go to the Users tab of the Administration page, click “edit” for the user you want to figure out their username, and get the username from the dialog window that opens. If the Add-on Tool Target URL is a Data Lab Notebook, then any permissions set on the Add-on Tool will also be added to the target Project as users are required to have at least write permissions on the Data Lab Project to run the Notebook. Passing an empty list will remove permissions to the tool for all users (without modifying permissions to the Target URL). If the tool exists, set update_permissions to True to overwrite the previous Users permissions. If the tool exists and update_permissions is False, then permissions will not update.
ID	Optional. The ID of an existing Add-on tool. Only needed if you want to update an already installed Add-on tool or its permissions. update_tool or update_permissions must be set to True if you want to update an existing tool.

include_workbook_parameters (bool, default True) – If True, the workbookId, worksheetId, workstepId, and/or seeqVersion are passed from the launched workbook through the URL as query parameters after the “.ipynb?”. For example: https://my.seeq.com/data-lab/<id>/addon/TEST.ipynb?workbookId={workbookId}&worksheetId={ worksheetId}&workstepId={workstepId}&seeqVersion={seeqVersion}
update_tool (bool, default False) – False will prevent an existing Add-on tool to be updated. True will update an existing Add-on tool. You must supply the ID of the tool(s) that you want to update.
update_permissions (bool, default False) – False will prevent changing the current permissions on an existing Add-on tool and its Target URL. True will modify the current permissions on an existing Add-on tool as well as its Target URL. You must supply the ID of the tool(s) that you want to update its (their) permissions.
in_development (bool, default False) – True will allow to install the Add-on tool for the use of the user installing the Add-on, even if such user is not an administrator.
errors ({'raise', 'catalog'}, default 'raise') – If ‘raise’, any errors encountered will cause an exception. If ‘catalog’, errors will be added to a ‘Result’ column in the status.df DataFrame.
quiet (bool, default False) – If True, suppresses progress output. Note that when status is provided, the quiet setting of the Status object that is passed in takes precedence.
status (spy.Status, optional) – If specified, the supplied Status object will be updated as the command progresses. It gets filled in with the same information you would see in Jupyter in the blue/green/red table below your code while the command is executed. The table itself is accessible as a DataFrame via the status.df property.
session (spy.Session, optional) – If supplied, the Session object (and its Options) will be used to store the login session state. This is useful to log in to different Seeq servers at the same time or with different credentials.

Notes

Setting the Target URL to a non-Add-on Mode Data Lab project should be avoided. Non-Add-on Mode Data Lab projects would get their own container but technical limitations dictate that each container accesses the same files on a shared volume. This results in unwanted interactions, save notifications, and a last-save-wins behavior.

Returns:

A DataFrame with the metadata of the Add-on tools pushed, along with any errors and statistics about the operation.

Additionally, the following properties are stored on the “spy” attribute of the output DataFrame:

Property	Description
func	A str value of ‘spy.addons.install’
kwargs	A dict with the values of the input parameters passed to spy.addons.install to get the output DataFrame
status	A spy.Status object with the status of the spy.addons.install call

Return type:

pandas.DataFrame

Examples

Install a new Add-on tool >>> my_new_tool = { >>> “Name”: ‘My New Tool’, >>> “Description”: “this is an awesome tool”, >>> “Target URL”: “https://www.my.seeq.com/data-lab/8FB008FF-ECF0-4837-B3D4-7FCBB49CC108/addon/my_tool.ipynb”, >>> “Groups”: [‘My Seeq Group’]}

>>> df_installed = spy.addons.install(my_new_tool)

If the tool already existed and you want to update it >>> df_installed = spy.addons.install(my_new_tool, update_tool=True)

To installed multiple tools at once: >>> new_tools = [ >>> { >>> “Name”: ‘My New Tool’, >>> “Description”: “this is an awesome tool”, >>> “Target URL”: “https://my.seeq.com/data-lab/8FB008FF-ECF0-4837-B3D4-7FCBB49CC108/addon/my_tool.ipynb”, >>> “Icon”: “fa fa-bell”, >>> “Groups”: [‘My Seeq Group’]}, >>> { >>> “Name”: ‘Your New Tool’, >>> “Description”: “this is an awesome tool”, >>> “Target URL”: “https://my.seeq.com/data-lab/F4DS345D-23DS-2344-SVSE-345234TSDF52/addon/tool2.ipynb”, >>> “Icon”: “fa fa-bars”, >>> “Groups”: [‘Everyone’]}]

>>> df_installed = spy.addons.install(new_tools)

Or set the properties in a pd.DataFrame (useful when modifying existing tools by manipulating the pd.DataFrame from spy.addons.search):

>>> searched_tools = spy.addons.search({"Link Type": "window"})
>>> searched_tools["Link Type"] = ['tab'] * len(searched_tools)
>>> df_installed = spy.addons.install(searched_tools,update_tool=True)

To change group permissions: >>> searched_tools = spy.addons.search({“Name”: “My New Tool”}) >>> searched_tools[“Groups”] = [[‘Everyone’]] * len(searched_tools) >>> df_installed = spy.addons.install(searched_tools,update_permissions=True)

To change user permissions >>> searched_tools = spy.addons.search({“Name”: “My New Tool”}) >>> searched_tools[“Users”] = [[‘user@my.seeq.com’]] * len(searched_tools) >>> df_installed = spy.addons.install(searched_tools,update_permissions=True)

Issues a query to the Seeq Server to retrieve metadata for Add-on tools. This metadata can be used to update or uninstall Add-on tools.

Parameters:

query ({str, dict, list, pd.DataFrame, pd.Series}) –

A mapping of property / match-criteria pairs

If you supply a dict or list of dicts, then the matching operations are “contains” (instead of “equal to”).

If you supply a DataFrame or a Series, then the matching operations are “equal to” (instead of “contains”).

’Name’ field allows you to query all installed Add-on Tools by using the wildcard ‘*’.

Available options are:

Property	Description
ID	The ID of the Add-on tool
Name	The name of the Add-on tool
Description	The description of the Add-on tool
Target URL	The URL that the Add-on opens
Icon	Name of the fontawesome icon class displayed on the Add-on tool
Launch Location	The Location of the Add-on tool. Either “homescreen” or “toolsPane”
Link Type	Display characteristics of the Add-on tool. Either “window”, “tab” or None
Window Details	Display characteristics used when linkType is set to “window”
Sort Key	Determines the order in which the Add-on Tools are displayed in the tool panel
Reuse Window	True or False.

errors ({'raise', 'catalog'}, default 'raise') – If ‘raise’, any errors encountered will cause an exception. If ‘catalog’, errors will be added to a ‘Result’ column in the status.df DataFrame.
quiet (bool, default False) – If True, suppresses progress output. Note that when status is provided, the quiet setting of the Status object that is passed in takes precedence.
status (spy.Status, optional) – If specified, the supplied Status object will be updated as the command progresses. It gets filled in with the same information you would see in Jupyter in the blue/green/red table below your code while the command is executed. The table itself is accessible as a DataFrame via the status.df property.
session (spy.Session, optional) – If supplied, the Session object (and its Options) will be used to store the login session state. This is useful to log in to different Seeq servers at the same time or with different credentials.

Returns:

A DataFrame with rows for each item found and columns for each property.

Additionally, the following properties are stored on the “spy” attribute of the output DataFrame:

Property	Description
func	A str value of ‘spy.addons.search’
kwargs	A dict with the values of the input parameters passed to spy.addons.search to get the output DataFrame
status	A spy.Status object with the status of the spy.addons.search call

Return type:

pandas.DataFrame

Examples

Search for all the currently installed Add-on tools

>>> search_results = spy.addons.search({'Name': '*'})

To access the stored properties: >>> search_results.spy.kwargs >>> search_results.spy.status

Search for an Add-on given its ID

>>> search_results = spy.addons.search({"ID": "B540FF01-56B7-43AD-AE81-67AACB36C7F3"})

Search for multiple Add-ons in the same spy.addons.search call:

>>> search_results = spy.addons.search([{"Name": "Tool Name"}, {'Target URL': 'https://www.google.com'}])

Search for multiple Add-ons using a pd.DataFrame

>>> my_items = pd.DataFrame(
>>>     {'Name': ['My Tool Name', 'Awesome Tool'],
>>>      'Link Type': 'window'})
>>> spy.addons.search(my_items)

seeq.spy.addons.uninstall(items: DataFrame | Series, *, errors: str | None = None, quiet: bool | None = None, status: Status = None, session: Session | None = None) → DataFrame

Uninstalls Add-on Tool from the Seeq Workbench. It does not remove the target_url contents. Uninstalling Add-on tools requires administrator access.

Parameters:

items ({pd.DataFrame, pd.Series}) – A DataFrame or Series containing ID column that can be used to identify the Add-on tool to uninstall. This is usually created via a call to spy.addons.search().
errors ({'raise', 'catalog'}, default 'raise') – If ‘raise’, any errors encountered will cause an exception. If ‘catalog’, errors will be added to a ‘Result’ column in the status.df DataFrame.
quiet (bool) – If True, suppresses progress output. Note that when status is provided, the quiet setting of the Status object that is passed in takes precedence.
status (spy.Status, optional) – If specified, the supplied Status object will be updated as the command progresses. It gets filled in with the same information you would see in Jupyter in the blue/green/red table below your code while the command is executed. The table itself is accessible as a DataFrame via the status.df property.
session (spy.Session, optional) – If supplied, the Session object (and its Options) will be used to store the login session state. This is useful to log in to different Seeq servers at the same time or with different credentials.

Returns:

A DataFrame with the metadata of the Add-on tools uninstalled, along with any errors and statistics about the operation.

Additionally, the following properties are stored on the “spy” attribute of the output DataFrame:

Property	Description
func	A str value of ‘spy.addons.uninstall’
kwargs	A dict with the values of the input parameters passed to spy.addons.uninstall to get the output DataFrame
status	A spy.Status object with the status of the spy.addons.uninstall call

Return type:

pandas.DataFrame

Examples

Search for a tool with a specific name and uninstall it

>>> search_results = spy.addons.search({'Name': 'Obsolete Tool'})
>>> uninstalled_tool = spy.addons.uninstall(search_results)