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 Show	Boolean if the axis should be shown	Si, Sc, M
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
Axis Align	Specify the side of the plot for the y-axis. ‘Left’ (default) or ‘Right’.	Si, Sc, M
Line Style	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 Display	The sample display style. Options are ‘Line’, ‘Line and Sample’, ‘Samples’, ‘Bars’	Si
Selected	Boolean indicating if item should be selected	All
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 ItemInventoryProgress(scraped: 'int', expected: 'int'): Bases: object

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, include_access_control: bool = True, specific_worksheet_ids: List[str] | None = None, as_template_with_label: str = 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.
include_access_control (bool, default True) – If True, includes the access control information for the workbook and all worksheets.
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.
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. 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, assume_dependencies_exist: bool = False, 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.
assume_dependencies_exist (bool, default False) – If True, then the push operation will assume that any dependencies not found in the set of workbooks pushed are already present on the target server. This is useful, for example, when you are pushing a subset of workbooks (like a single Organizer Topic) and don’t need or want to push all of the referenced Workbench Analyses.
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') –

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