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 ofspy.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 ofspy.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.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 trend_toolbar
Trend toolbar for configuring the worksheet’s trend toolbar settings.
- 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.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