SPy Utilities

seeq.spy.utils.get_data_lab_project_id()

Get Seeq ID assigned to this Data Lab Project

Returns:: The Seeq ID as a string, or None if no ID assigned
Return type:: {str, None}

seeq.spy.utils.get_data_lab_project_id_from_url(url)

Get the Seeq DataLab Project ID from a URL

Given a URL copied from a browser or from an API response ‘href’ attribute, get the URL of the DataLab project.

Parameters:: url (str) – The URL
Returns:: The Seeq ID as a string, or None if no project ID was found
Return type:: {str, None}

seeq.spy.utils.get_data_lab_project_url(use_private_url=True)

Get Data Lab Project URL in form of {Seeq_Server_URL}/data-lab/{Data Lab Project ID}

Parameters:: use_private_url (bool, default True) – If False, use the publicly accessible Seeq url for the Seeq_Server_URL
Returns:: The Data Lab Project URL as a string
Return type:: {str}

seeq.spy.utils.get_open_port() → int

Finds an open port on the host machine and returns it.

Returns:: An open port number
Return type:: {int}
Raises:: {RuntimeError} – If no open ports are found

seeq.spy.utils.get_sdk_module_version_tuple() → Tuple[int, int, int]

Provides a tuple of (major, minor, patch) version of Seeq SDK module (as integers).

The major version of the Seeq SDK should match the major version of the Seeq Server. You can retrieve the version of the Seeq Server (once you’ve logged in) via spy.utils.get_server_version_tuple().

Use this function instead of parsing sdk.__version__.

Return type:: Tuple of (major, minor, patch) version of Seeq SDK module (as integers).

seeq.spy.utils.get_server_version_tuple(session: Session) → Tuple[int, int, int]

Provides a tuple of (major, minor, patch) version of the Seeq Server the supplied session is connected to (as integers). If a session is not supplied, the default session is used.

The major version of the Seeq SDK should match the major version of the Seeq Server. You can retrieve the version of the Seeq Server (once you’ve logged in) via spy.utils.get_server_version_tuple().

Use this function instead of parsing sdk.__version__.

Parameters:: session (spy.Session, optional) – If supplied, the Session object used for the connection to Seeq Server. If not supplied, the default session is used.
Return type:: Tuple of (major, minor, patch) version of Seeq Server (as integers).

seeq.spy.utils.get_spy_module_version_tuple() → Tuple[int, int]

Provides a tuple of (major, minor) version of Seeq SPy module (as integers).

Use this function instead of parsing spy.__version__.

Return type:: Tuple of (major, minor) version of Seeq SPy module (as integers).

seeq.spy.utils.get_user_timezone(session: Session, default_tz='UTC')

Returns the preferred timezone of the user currently logged in, or default_tz if there is no user currently logged in.

Param:: session: The login session (necessary to fulfill this call).
Param:: default_tz: The default timezone to return if no user is logged in.
Returns:: The user’s preferred timezone, in IANA Time Zone Database format (e.g., ‘America/New York’)
Return type:: str

seeq.spy.utils.get_workbook_id_from_url(url)

Get the Seeq ID of a workbook from a URL

Given a URL copied from a browser or from an API response ‘href’ attribute, get the URL of the workbook.

Parameters:: url (str) – The URL
Returns:: The Seeq ID as a string, or None if no workbook ID was found
Return type:: {str, None}

seeq.spy.utils.get_worksheet_id_from_url(url)

Get the Seeq ID of a worksheet from a URL

Given a URL copied from a browser or from an API response ‘href’ attribute, get the URL of the worksheet.

Parameters:: url (str) – The URL
Returns:: The Seeq ID as a string, or None if no worksheet ID was found
Return type:: {str, None}

seeq.spy.utils.get_workstep_id_from_url(url)

Get the Seeq ID of a workstep from a URL

Given a URL copied from a browser or from an API response ‘href’ attribute, get the URL of the workstep.

Note that URLs from a browser rarely specify the workstep. URLs that contain the workstep normally come from links in Organizer Topic Documents or href attributes in API outputs.

Parameters:: url (str) – The URL
Returns:: The Seeq ID as a string, or None if no workstep ID was found
Return type:: {str, None}

seeq.spy.utils.is_guid(s: object)

Determine if an object is a string GUID/UUID

Parameters:: s (object) – The object to be tested
Returns:: True if the object is a string GUID/UUID, False otherwise
Return type:: bool

seeq.spy.utils.is_sdk_module_version_at_least(required_major: int, required_minor: int = 0, required_patch: int = 0) → bool

Use this function to ensure that the SDK module meets a version requirement.

Parameters:

required_major (int) – The SDK major version that your notebook/script/application requires.
required_minor (int, default 0) – The SDK minor version that your notebook/script/application requires.
required_patch (int, default 0) – The SDK patch version that your notebook/script/application requires.

Return type:

True if the SDK version is equal to or greater than the version specified.

seeq.spy.utils.is_server_version_at_least(required_major: int, required_minor: int = 0, required_patch: int = 0, session: Session | None = None) → bool

Use this function to ensure that the Seeq Server meets a version requirement.

Parameters:

required_major (int) – The Seeq Server major version that your notebook/script/application requires.
required_minor (int, default 0) – The Seeq Server minor version that your notebook/script/application requires.
required_patch (int, default 0) – The Seeq Server patch version that your notebook/script/application requires.
session (spy.Session, optional) – If supplied, the Session object used for the connection to Seeq Server. If not supplied, the default session is used.

Return type:

True if the Seeq Server version is equal to or greater than the version specified.

seeq.spy.utils.is_spy_module_version_at_least(required_major: int, required_minor: int = 0) → bool

Use this function to ensure that the SPy module meets a version requirement.

Parameters:

required_major (int) – The SPy major version that your notebook/script/application requires.
required_minor (int, default 0) – The SPy minor version that your notebook/script/application requires.

Return type:

True if the SPy version is equal to or greater than the version specified.

seeq.spy.utils.is_valid_unit(session: Session, unit)

Returns True if the supplied unit will be recognized by the Seeq calculation engine. This can be an important function to use if you are attempting to supply a “Value Unit Of Measure” property on a Signal or a “Unit Of Measure” property on a Scalar.

Param:: session: The login session (necessary to execute this call)
Param:: unit: The unit of measure for which to assess validity
Returns:: True if unit is valid, False if not

seeq.spy.utils.parse_schedule_string(schedule_string: str) → str

Parses a human-readable schedule description into a cron expression.

Parameters:: schedule_string (str) – A human-readable schedule description. This string should contain information about the timing and frequency of an event or task, such as “Every day at 8 AM”.
Returns:: A cron expression representing the schedule described in schedule_string.
Return type:: str

Examples

>>> parse_schedule_string("Every day at 8 AM")
'0 0 8 */1 * ?'
>>> parse_schedule_string("Every 15th day of the month at 6:30 PM")
'0 30 18 15 */1 ?'

seeq.spy.utils.parse_str_time(str_time: str) → Tuple[float, str, float]

Given a string time like 5min, 3hr, 2d, 7mo, etc, get the numeric and unit portions and calculate the total number of milliseconds. Time units will be converted to the Seeq canonical versions, eg, ‘sec’ will yield ‘s’. For example ‘5min’ returns (5, ‘min’, 300000)

Param:: str_time: A string representing a time. Eg, 3min
Returns:: tuple (numeric portion, string unit, total milliseconds)

seeq.spy.utils.pull_worksheet_via_url(url: str, *, minimal: bool = True, include_archived: bool = False, quiet: bool | None = False, session: Session | None = None)

Get a worksheet from a valid Workbench Analysis URL.

Parameters:

url (str) – The URL of the Workbench Analysis
minimal (bool, default True) – If True, only the minimal amount of information will be pulled from the server. This is useful if you are only interested in, for example, knowing what display_items are present.
include_archived (bool, default False) – If True, returns the worksheet even if the workbook is archived. If False, raises an exception if the workbook is archived.
quiet (bool, default False) – If True, suppresses progress output.
session (spy.Session, optional) – If supplied, the Session object used for the connection to Seeq Server. If not supplied, the default session is used.

Returns:

The Worksheet object

Return type:

{Worksheet}

seeq.spy.utils.time_abbreviation_to_ms_multiplier(abbreviation)

Given a time abbreviation, returns a multiplier that converts the time value to ms and the canonical version of that time abbreviation. For example, “6 sec”, pass the “sec” to this function and it will return (1000, ‘s’). Multiplying 6 by 1000 gives the duration in ms.

Parameters:: abbreviation (str) – The time abbreviation. Acceptable values are: s, sec, second, seconds min, minute, minutes h, hr, hour, hours d, day, days w, wk, wks, week, weeks m, mo, month, months y, yr, yrs, year, years
Returns:: The multiplier to convert from the time basis to ms and the canonical version of the unit
Return type:: (int, str)