SPy Workbooks

Constants

seeq.spy.workbooks.ALL

Top-level workbook directory that can be used in a workbook path argument

seeq.spy.workbooks.CORPORATE

Top-level workbook directory that can be used in a workbook path argument

seeq.spy.workbooks.FORCE_ME_AS_OWNER

Use as input for owner argument of spy.workbooks.push to assign ownership of the pushed content to the logged-in user

seeq.spy.workbooks.MY_FOLDER

Top-level workbook directory that can be used in a workbook path argument

seeq.spy.workbooks.ORIGINAL_OWNER

Use as input for owner argument of spy.workbooks.push to assign ownership of the pushed content to the original owner of the pulled content

seeq.spy.workbooks.PUBLIC

Top-level workbook directory that can be used in a workbook path argument

seeq.spy.workbooks.SHARED

Top-level workbook directory that can be used in a workbook path argument

seeq.spy.workbooks.USERS

Top-level workbook directory that can be used in a workbook path argument

Classes

class seeq.spy.workbooks.Analysis(*args, **kwargs)

Bases: Workbook

class seeq.spy.workbooks.AnalysisWorksheet(*args, **kwargs)

Bases: Worksheet

static add_display_columns(df, inplace=True)

Add the display attribute columns to a pandas.DataFrame

Parameters:
  • df (pandas.DataFrame) – The DataFrame that will have the columns added

  • inplace (boolean, default True) – If True, the columns of the DataFrame passed in will be modified and None will be returned. If False a copy of df with the new columns will be returned

Returns:

None if inplace == True. A pandas.DataFrame deep copy with the display attribute columns added if inplace == False

Return type:

{None, pandas.DataFrame}

property display_items

Add items to the display pane.

Items in the input data frame that do not have a known store will be skipped.

Parameters:

value (dict, pd.DataFrame, pd.Series) –

A pandas DataFrame with the items to be added to the display. It must minimally have ‘ID’ and ‘Type’ columns. Display attributes should be in named columns as described below.

Type Key: Si = Signal, Sc = Scalar, C = Condition, M = Metric, T = Table

Display Attribute

Description

Applicability

Color

A 3-part RGB hexadecimal color spec starting with “#”. E.g. #CE561B

All

Axis Auto Scale

Boolean if the axis should auto scale

Si, Sc, M

Axis Limits

A dict of {‘min’: float, ‘max’: float} to specify the axis limits. Ignored if Auto Axis Scale is True.

Si, Sc, M

Axis Group

An identifier to specify shared axes

Si, Sc, M

Lane

The lane a trend is plotted in

Si, Sc, M

Align

Specify the side of the plot for the y-axis. ‘Left’ (default) or ‘Right’.

Si, Sc, M

Line

The trend line style. Options are ‘Solid’, ‘Dot’, ‘Short Dash’, ‘Long Dash’, ‘Short Dash-Dot’, ‘Short Dash-Dot-Dot’, ‘Long Dash-Dot’, ‘Long Dash-Dot-Dot’, ‘Dash-Dot’

Si, Sc, M

Line Width

The width of the line.

Si, Sc, M

Samples

The sample display style. Options are ‘Line’, ‘Line and Sample’, ‘Samples’, ‘Bars’

Si

Stack

Boolean indicating if bars should be stacked

T

Returns:

A DataFrame with all items displayed on the worksheet, including display settings.

Return type:

pd.DataFrame

property display_range

Set the display range on the worksheet

Parameters:

value (pandas.DataFrame, pandas.Series, dict) – The display range as a single row DataFrame, Series or dict with columns of ‘Start’ and ‘End’ containing the datetime objects or text parsable using pandas.to_datetime().

Returns:

A dict with keys of ‘Start’ and ‘End’ and values of the ISO8601 timestamps for the start and end of the display range.

Return type:

dict

property html

Get/Set the raw HTML for the journal

property investigate_range

Set the investigate range on the worksheet

Parameters:

value (pandas.DataFrame, pandas.Series, dict) – The investigate range as a single row DataFrame, Series or dict with columns of ‘Start’ and ‘End’ containing the datetime objects or text parsable using pandas.to_datetime().

Returns:

A dict with keys of ‘Start’ and ‘End’ and values of the ISO8601 timestamps for the start and end of the investigate range.

Return type:

dict

property journal

Returns the “Journal” object, which is an “Annotation” that houses the HTML and other metadata about the Journal attached to this worksheet.

pull_current_workstep(quiet: bool = False, status: Status | None = None, session: Session | None = None)

Pulls the current workstep for the given worksheet so that the Python object has been updated with what the user might have changed in the user interface.

Parameters:
  • 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.

Example

>>> worksheet = workbook.worksheets['My Worksheet']
>>> worksheet.pull_current_workstep()
push_current_workstep(quiet: bool = False, status: Status | None = None, session: Session | None = None)

Pushes a new workstep for the given worksheet using the current in-memory value given by current_workstep().

Parameters:
  • 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.

Example

>>> worksheet = workbook.worksheets['My Worksheet']
>>> worksheet.display_items = worksheet.display_items.drop(
>>>     worksheet.display_items[worksheet.display_items['Name'] == 'Temperature'].index)
>>> worksheet.push_current_workstep()
property scatter_plot_series

Get/Set the IDs of the item plotted on the x-axis of a scatter plot

Parameters:

value (dict or None) – A dict with keys of the axis name (either ‘X’ or ‘Y’) and values of dicts, Series, or one-row DataFrames with a column of ‘ID’ for the item to use for the axis.

Returns:

A dict with keys of ‘X’ and ‘Y’ and values of dicts with a key of ‘ID’ and a value of either the Seeq ID of the item or None if not specified. Returns None if neither is specified

Return type:

dict or None

Example

>>> series = worksheet.scatter_plot_series
>>> print(series)
    {
        'X': {'ID': '57ADF442-C571-4B19-B358-E03D77CE68B4'},
        'Y': {'ID': '3E4571C8-66C0-428E-8B04-FE0FB9F140BB'}
    }
property table_date_display

The dates that should be displayed for tables. Valid values are:

Date Display

Result

None

No date display

‘Start’

Start of the time period only

‘End’

End of the time period only

‘Start And End’

Start and end of the time period

property table_date_format

The string defining the date format. Formats are parsed using momentjs. The full documentation for the momentjs date parsing can be found at https://momentjs.com/docs/#/displaying/

Examples

“d/m/yyy” omitting leading zeros (eg, 4/27/2020): l “Mmm dd, yyyy, H:MM AM/PM” (eg, Apr 27, 2020 5:00 PM) : lll “H:MM AM/PM” (eg, “5:00 PM”): LT

property table_mode

The string defining the Table view mode. Can be either “simple” or “condition”.

property view

The current view for the workstep. Valid values are

View

Result

Trend

Show the time-series trend view (default)

Scatter Plot

Show the scatter plot view

Treemap

Show the treemap view

Scorecard

Show the table view

Table

Show the table view

class seeq.spy.workbooks.Annotation(worksheet, annotation_type)

Bases: Item

add_image(*, filename=None, buffer=None, image_format=None, placement=None, just_src=False)

Add an image to the annotation.

Parameters:
  • filename (str) – The full path to the image file

  • buffer (str) – The bytes of the image in memory (must also specify image_format)

  • image_format – The image format of what is supplied in bytes (e.g. ‘png’, ‘jpg’)

  • placement ({'end', 'beginning', None}, default None) – The location to add the image to an existing document.

  • just_src (bool) – False if full <img> html tags desired, True if you just want the url to put in the <img src=”<url>”> attribute yourself.

class seeq.spy.workbooks.AssetSelection(definition, report)

Bases: Item

The SPy representation of a Seeq asset selection.

Input Column

Asset Selection Attribute

ID

The id of the asset selection. If not provided one will be generated

Name

The name of the asset selection. Eg “Asset Selection 1”

Asset ID

The id of the asset selected

Path Levels

Number of levels shown in the asset path for the asset selection

class seeq.spy.workbooks.Content(definition, report=None)

Bases: Item

The SPy representation of a Seeq Content Item. Content can be created with a number of different sizing parameters defined in the display() function within an HTML template.

If no size, shape, width, or height are specified in the display() function, size and shape will default to medium and rectangle, respectively. If a height and width are specified, they will take precedence over size and shape. A height must be specified with a width and vice-versa.

Input Column

Content Size Attribute

Size

The size of the content. Can be ‘small’, ‘medium’, or ‘large’. Defaults to ‘medium’

Shape

The content’s shape. Can be ‘strip’, ‘rectangle’, or ‘square’. Defaults to ‘rectangle’

Height

The height of the content. Takes precedence over the size/shape parameter, if specified

Width

The width of the content. Takes precedence over the size/shape parameter, if specified

Scale

The content’s desired scale. A value greater than 1 will increase the size of elements within the screenshot. A value less than 1 will shrink the size of elements within the screenshot

selector

The content’s css styling. The ‘.screenshotSizeToContent’ style can be used to trim whitespace content, which is useful for tables, which have an arbitrary shape. Defaults to None.

class seeq.spy.workbooks.DateRange(definition, report)

Bases: Item

The SPy representation of a Seeq date range. Date ranges can be created with a number of different input properties that a user can define when creating a Date Range asset. Date ranges can either be static, specified with just a Name, Start, and End, or they can be live, denoted by including Auto Enabled, Auto Duration, Auto offset, and Auto Offset Direction values.

Input Column

Date Range Attribute

ID

The id of the date range. If not provided one will be generated

Name

The name of the date range. Eg “Date Range 1”

Start

The ISO 8601 string or datetime object start of the date range

End

The ISO 8601 string or datetime object end of the date range

Auto Enabled

Boolean if automatic update is enabled

Auto Duration

The duration of the automatic update sliding window. Eg, 10min, 1hr, 1d, etc

Auto Offset

The offset of the automatic update sliding window. Eg, 10min, 1day, etc

Auto Offset Direction

The direction of the offset. Either ‘Past’ or ‘Future’. Default ‘Past’

Condition ID

The id of the condition defining the date range, if applicable

class seeq.spy.workbooks.Item(definition=None, *, provenance=None)

Bases: object

The base class of all objects in the spy.workbooks module that represent items in Seeq. Each item is described by the dictionary stored at its dictionary property.

property fqn

The “fully qualified name” (FQN) of this item, which includes the Path and Asset (if present). For example: “Example >> Cooling Tower 1 >> Area A >> Temperature” :return: The fully qualified name of this item.

class seeq.spy.workbooks.Journal(worksheet)

Bases: Annotation

class seeq.spy.workbooks.Report(worksheet)

Bases: Annotation

class seeq.spy.workbooks.Topic(*args, **kwargs)

Bases: Workbook

class seeq.spy.workbooks.TopicDocument(*args, **kwargs)

Bases: Worksheet

property html

Get/Set the raw HTML for the topic document

property report

Returns the “Report” object, which is an “Annotation” that houses the HTML and other metadata about the TopicDocument. This object also includes dictionaries that contain the Content, DateRange and AssetSelection objects.

property schedule

Get/Set the schedule for the topic document. The schedule determines whether a document is a live, auto-updating document or a scheduled document.

Parameters:

value (dict or None) –

A dictionary of a ‘Background’ and a ‘Cron Schedule’ for document’s schedule

Input Column

Schedule Attribute

Background

Whether the document is scheduled or live

Cron Schedule

The document’s update schedule as a cron schedule. This should be a list of cron expressions such as [‘0 */5 * * * ?’]. See http://www.quartz-scheduler.org/documentation/quartz-2.3.0/tutorials/crontrigger.html for more information

Returns:

The current dictionary containing the ‘Background’ variable and ‘Cron Schedule’ for the document’s schedule

Return type:

dict

class seeq.spy.workbooks.Workbook(*args, **kwargs)

Bases: ItemWithOwnerAndAcl

class seeq.spy.workbooks.Worksheet(*args, **kwargs)

Bases: Item

property fqn

The “fully qualified name” (FQN) of this item, which includes the Path and Asset (if present). For example: “Example >> Cooling Tower 1 >> Area A >> Temperature” :return: The fully qualified name of this item.

property timezone

The string name of the worksheet’s current timezone or None if one is not set

property url

The URL of the worksheet. Note that value won’t be filled if the workbook/worksheet hasn’t been pulled from Seeq.

Functions

seeq.spy.workbooks.load(folder_or_zipfile, *, as_template_with_label: str = None, errors: str | None = None, quiet: bool | None = None, status: Status | None = None) WorkbookList

Loads a list of workbooks from a folder on disk into Workbook objects in memory.

Parameters:
  • folder_or_zipfile (str) – A folder or zip file on disk containing workbooks to be loaded. Note that any subfolder structure will work – this function will scan for any subfolders that contain a Workbook.json file and assume they should be loaded.

  • as_template_with_label (str) – Causes the workbooks to be loaded as templates (either AnalysisTemplate or TopicTemplate) with the label specified. See the Workbook Templates documentation notebook for more information about templates.

  • 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 (errors=’catalog’ must be combined with status=<Status object>).

  • 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.

seeq.spy.workbooks.pull(workbooks_df: DataFrame | str, *, include_referenced_workbooks: bool = True, include_inventory: bool = True, include_annotations: bool = True, include_images: bool = True, include_rendered_content: bool = False, specific_worksheet_ids: List[str] | None = None, errors: str | None = None, quiet: bool | None = None, status: Status | None = None, session: Session | None = None) WorkbookList | None

Pulls the definitions for each workbook specified by workbooks_df into memory as a list of Workbook items.

Parameters:
  • workbooks_df ({str, pd.DataFrame}) – A DataFrame containing ‘ID’, ‘Type’ and ‘Workbook Type’ columns that can be used to identify the workbooks to pull. This is usually created via a call to spy.workbooks.search(). Alternatively, you can supply a workbook ID directly as a str or the URL of a Seeq Workbench worksheet as a str.

  • include_referenced_workbooks (bool, default True) – If True, Analyses that are depended upon by Topics will be automatically included in the resulting list even if they were not part of the workbooks_df DataFrame.

  • include_inventory (bool, default True) – If True, all items that are referenced in worksheets, journals, topics etc are included in the Workbook object’s “inventory”, along with anything that is scoped to the workbook.

  • include_annotations (bool, default True) – If True, downloads the HTML for Journal and Organizer Topic content.

  • include_images (bool, default True) – If True, downloads all static images (not including embedded content – see include_rendered_content for that).

  • include_rendered_content (bool, default False) – If True, any Organizer Topics pulled will include rendered content images, which will cause spy.workbooks.save() to include a folder for each Topic Document with its HTML and images such that it can be loaded and viewed in a browser.

  • specific_worksheet_ids (List[str], default None) – If supplied, only the worksheets with IDs specified in the supplied list will be pulled. This should be used when it would otherwise take too long to pull all worksheets and you’re only interested in a small subset. Be careful not to push the resulting workbook(s) back because the other worksheets will get archived.

  • 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 (errors=’catalog’ must be combined with status=<Status object>).

  • 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.

seeq.spy.workbooks.push(workbooks, *, path=None, owner=None, label=None, datasource=None, datasource_map_folder=None, use_full_path=False, access_control=None, override_max_interp=False, include_inventory=None, include_annotations: bool = True, scope_globals_to_workbook=False, refresh=True, lookup_df: DataFrame = None, specific_worksheet_ids: List[str] | None = None, create_dummy_items_in_workbook=None, errors=None, quiet=None, status: Status | None = None, session: Session | None = None, item_map: ItemMap | None = None) DataFrame

Pushes workbooks into Seeq using a list of Workbook object definitions.

Parameters:
  • workbooks ({Workbook, list[Workbook]}) – A Workbook object or list of Workbook objects to be pushed into Seeq.

  • path (str, default None) –

    A ‘>>’-delimited folder path to create to contain the workbooks. Note that a further subfolder hierarchy will be created to preserve the relative paths that the folders were in when they were searched for and pulled. If you specify None, then the workbook will stay where it is (if it has already been pushed once).

    If you specify spy.workbooks.MY_FOLDER, it will be moved to the user’s home folder.

    If you specify a folder ID directly, it will be pushed to that folder.

    If you specify spy.workbooks.ORIGINAL_FOLDER, it will be pushed to the folder it was in when it was originally pulled. The folder hierarchy will be recreated on the target server if it doesn’t already exist. (You must be an admin to use this to ensure you have permissions to put things where they need to go.)

  • owner (str, default None) –

    Determines the ownership of pushed workbooks and folders.

    By default, the current owner will be preserved. If the content doesn’t exist yet, the logged-in user will be the owner.

    All other options require that the logged-in user is an admin:

    If spy.workbooks.ORIGINAL_OWNER, ownership is assigned according to the original owner of the pulled content. (You must be an admin to use this.)

    If spy.workbooks.FORCE_ME_AS_OWNER, existing content will be reassigned to the logged-in user.

    If a username or a user’s Seeq ID is supplied, that user will be assigned as owner.

    You may need to supply an appropriate datasource map if the usernames are different between the original and the target servers.

  • label (str) – A user-defined label that differentiates this push operation from others. By default, the label will be the logged-in user’s username OR the username from the ‘owner’ argument so that push activity will generally be isolated by user. But you can override this with a label of your choosing.

  • datasource (str, optional, default 'Seeq Data Lab') –

    The name of the datasource within which to contain all the pushed items. Items inherit access control permissions from their datasource unless it has been overridden at a lower level. If you specify a datasource using this argument, you can later manage access control (using spy.acl functions) at the datasource level for all the items you have pushed.

    If you instead want access control for your items to be inherited from the workbook they are scoped to, specify spy.INHERIT_FROM_WORKBOOK.

  • datasource_map_folder (str, default None) – A folder containing Datasource_Map_Xxxx_Yyyy_Zzzz.json files that can provides a means to map stored items (i.e., those originating from external datasources like OSIsoft PI) from one server to another or from one datasource to another (i.e., for workbook swapping). A default set of datasource map files is created during a pull/save sequence, and you can copy these default files to a folder, alter them, and then specify the folder as this argument.

  • use_full_path (bool, default False) – If True, the original full path for an item is reconstructed, as opposed to the path that is relative to the Path property supplied to the spy.workbooks.search() call that originally helped create these workbook definitions. Note that this full path will still be inside the folder specified by the ‘path’ argument, if supplied.

  • access_control (str, default None) –

    Specifies how Access Control Lists should be treated, via the following keywords: add/replace,loose/strict

    • If None, then no access control entries are pushed.

    • If ‘add’, then existing access control entries will not be disturbed but new entries will be added.

    • If ‘replace’, then existing access control entries will be removed and replaced with the entries from workbook definitions.

    • If ‘loose’, then any unmapped users/groups from the workbook definitions will be silently ignored.

    • If ‘strict’, then any unmapped users/groups will result in errors.

    Example: access_control=’replace,loose’

  • override_max_interp (bool, default False) – If True, then the Maximum Interpolation overrides from the source system will be written to the destination system.

  • include_inventory (bool, optional) –

    If True, then all calculated items that are scoped to the workbook will be pushed as well.

    If omitted, SPy will push inventory in any non-template scenarios.

  • include_annotations (bool, default True) – If True, downloads the HTML for Journal and Organizer Topic content.

  • scope_globals_to_workbook (bool, default False) – If include_inventory=True and scope_globals_to_workbook=True, then all globally-scoped (aka “Available outside this analysis”) items will be scoped to the workbook. False if you want to actually push these items to the global scope.

  • refresh (bool, default True) – If True, then the Workbook objects that were supplied as input will be updated to be “fresh” from the server after the push. All identifiers will reflect the actual pushed IDs. Since refreshing takes time, you can set this to False if you don’t plan to make further modifications to the Workbook objects or use the new IDs.

  • lookup_df (pd.DataFrame, optional) – A DataFrame of item metadata that can be used to look up identifiers that correspond to template parameters (when pushing AnalysisTemplate objects). This argument is automatically specified by the spy.push() function.

  • specific_worksheet_ids (List[str], default None) – If supplied, only the worksheets with IDs specified in the supplied list will be pushed. This should be used when it would otherwise take too long to push all worksheets and you’re interested in optimizing the push operation. No existing worksheets will be archived or moved in their ordering.

  • create_dummy_items_in_workbook (str, optional) – If specified, then “dummy” items will be created for any stored items that are not successfully mapped to the target system. This is useful when you want to push a workbook to a system that doesn’t have the same datasources/items as the source system. The dummy items will be created in the target system’s “Seeq Data Lab” datasource and will have the same name as the original item, and no data. They will be scoped to the workbook specified.

  • 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 (errors=’catalog’ must be combined with status=<Status object>).

  • 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.

  • item_map – For internal use only.

Returns:

A DataFrame with status on the items pushed. The IDs for the pushed workbooks are in the “Pushed Workbook ID” column.

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

Property

Description

func

A str value of ‘spy.workbooks.push’

kwargs

A dict with the values of the input parameters passed to this function

input

The set of workbooks passed in to this function

output

The set of workbooks pulled from the server if refresh=True

datasource

The datasource that all pushed items will fall under (as a DatasourceOutputV1 object).

item_map

A dictionary of IDs that map from the input workbooks and inventory to the actual IDs as they were created/updated on the server

status

A spy.Status object with the status of the spy.push call

Return type:

pandas.DataFrame

seeq.spy.workbooks.save(workbooks, folder_or_zipfile: str | None = None, *, datasource_map_folder: str | None = None, include_rendered_content: bool = False, pretty_print_html=False, overwrite: bool = False, errors: str | None = None, quiet: bool | None = None, status: Status | None = None)

Saves a list of workbooks to a folder on disk from Workbook objects in memory.

Parameters:
  • workbooks ({Workbook, list[Workbook]}) – A Workbook object or list of Workbook objects to save.

  • folder_or_zipfile (str, default os.getcwd()) – A folder or zip file on disk to which to save the workbooks. It will be saved as a “flat” set of subfolders, no other hierarchy will be created. The string must end in “.zip” to cause a zip file to be created instead of a folder.

  • datasource_map_folder (str, default None) – Specifies a curated set of datasource maps that should accompany the workbooks (as opposed to the default maps that were created during the spy.workbooks.pull call).

  • include_rendered_content (bool, default False) – If True, creates a folder called RenderedTopic within each Topic Document folder that includes the embedded content such that you can load it in an offline browser. You are required to have pulled the workbooks with include_rendered_content=True.

  • pretty_print_html (bool, default False) – If True, this function will re-format the HTML of Topic Documents and Journals so that it is easy to read in a text editor. If False, the HTML will be written exactly as it is stored in Seeq Server. Note that setting this to True can cause some minor deviations in rendering after a round-trip (i.e. pull/save/load/push).

  • overwrite (bool, default False) – If True, will overwrite any existing folder or zip file.

  • 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 (errors=’catalog’ must be combined with status=<Status object>).

  • 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.

seeq.spy.workbooks.search(query, *, content_filter='owner', all_properties=False, recursive=False, include_archived=False, errors=None, quiet=None, status=None, session: Session | None = None)

Issues a query to the Seeq Server to retrieve metadata for workbooks. This metadata can be used to pull workbook definitions into memory.

Parameters:
  • query (dict) –

    A mapping of property / match-criteria pairs. Match criteria uses the same syntax as the Data tab in Seeq (contains, or glob, or regex). Available options are:

    Property

    Description

    ID

    ID of the workbook, as seen in the URL.

    Name

    Name of the workbook.

    Path

    Path to the workbook through the folder hierarchy.

    Description

    Description of the workbook.

    Workbook Type

    Either ‘Analysis’ or ‘Topic’.

  • content_filter (str, default 'owner') –

    The allowed_content_filter must be updated every time there is a change to the ItemWithOwner#Filter Filters workbooks according to the following possible values:

    Property

    Description

    owner

    Only content owned by the logged-in user.

    shared

    Only content shared specifically with the logged-in user. Note: To obtain the same results as you would when looking at the “Shared” tab in the Seeq home screen, use “sharedorpublic” (see below).

    public

    Only content shared with Everyone.

    sharedorpublic

    Content shared with Everyone or with the logged-in user

    corporate

    Only content in the Corporate folder

    all

    All content, across all users (logged-in user must be admin).

    users

    Every user’s home folder (logged-in user must be admin)

  • all_properties (bool, default False) – True if all workbook properties should be retrieved. This currently makes the search operation much slower as retrieval of properties for an item requires a separate call.

  • recursive (bool, default False) – True if workbooks further down in the folder path should be returned.

  • include_archived (bool, default False) – True if archived (aka “trashed”) folders/workbooks should be returned.

  • 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 workbook found and columns for each property.

Return type:

pandas.DataFrame