SPy ACL

seeq.spy.acl.pull(items: DataFrame | dict | list | str | Item, *, include_my_effective_permissions: bool = False, errors: str | None = None, quiet: bool | None = None, status: Status | None = None, session: Session | None = None) → DataFrame

Pulls access control entries for a set of items as specified by their IDs. The most common way to invoke this command is directly after having done a spy.search() and produced a DataFrame full of items to work with.

Parameters:

• items ({pandas.DataFrame, dict, list, str, Item}) –

  The item IDs to pull for. This argument can take the following form:

  • a DataFrame with an “ID” column

  • a single dict with an “ID” key

  • a list of dicts with “ID” keys

  • a single Workbook object

  • a list of Workbook objects

  • a single string representing the ID of the item

  • a list of strings representing the IDs of the items

  • a SPy Item instance

• include_my_effective_permissions (bool, default False) – If True, adds ‘Read/Write/Manage Permission’ columns to the output DataFrame that reflect the calling user’s permissions for the item.

• errors ({'raise', 'catalog'}, default 'raise') – If ‘raise’, any errors encountered will cause an exception. If ‘catalog’, errors will be added to a ‘Pull 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 the metadata for the items pulled and an ‘Access Control’ column with an embedded DataFrame in each cell that represents the Access Control List.

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

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

Return type:

pandas.DataFrame

Examples

Search for signals with the name ‘Humid’ on the asset tree under ‘Example >> Cooling Tower 1’, then retrieve ACLs for the results:

>>> search_results = spy.search({'Name': 'Humid', 'Path': 'Example >> Cooling Tower 1'})
>>> pull_results = spy.acl.pull(search_results)
>>> pull_results.at[0, 'Access Control']  # Retrieves an inner DataFrame representing the ACL

seeq.spy.acl.push(items: DataFrame | dict | list | str | Item, acl: DataFrame | dict | list, *, replace: bool = False, disable_inheritance: bool = None, errors: str | None = None, quiet: bool | None = None, status: Status | None = None, session: Session | None = None) → DataFrame

Pushes new access control entries against a set of items as specified by their IDs. The most common way to invoke this command is directly after having done a spy.search() or spy.push() and produced a DataFrame full of items to work with.

Parameters:

• items ({pandas.DataFrame, dict, list, str, Item}) –

  The item IDs to push against. This argument can take the following form:

  • a DataFrame with an “ID” column

  • a single dict with an “ID” key

  • a list of dicts with “ID” keys

  • a single Workbook object

  • a list of Workbook objects

  • a single string representing the ID of the item

  • a list of strings representing the IDs of the items

  • a SPy Item instance

• acl ({pandas.DataFrame, dict, list}) – The Access Control List can be either a Pandas DataFrame a list of dicts, or just a dict. The dict or DataFrame rows must consist of either ‘ID’ OR (‘Name’ or ‘Username’) to specify the identity and then a ‘Read’, ‘Write’ and/or ‘Manage’ entry that is a boolean True or False value.

• replace ({bool}, optional, default False) –

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

  • If True, then existing access control entries will be removed and replaced with the entries from the acl argument.

• disable_inheritance ({bool}, optional, default None) –

  • If None, then the inheritance will remain unchanged. (This is the default behavior.)

  • If False, then the ACL inherits from either the datasource or the workbook (for signals/scalars/conditions/assets/metrics). Workbooks inherit their ACLs from their parent folder.

  • If True, then the ACL will no longer inherit from the parent.

• errors ({'raise', 'catalog'}, default 'raise') – If ‘raise’, any errors encountered will cause an exception. If ‘catalog’, errors will be added to a ‘Push 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 the metadata for the items pushed, along with any errors (in the ‘Push Result’ column).

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

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

Return type:

pandas.DataFrame

Examples

Search for signals with the name ‘Hydrocracker’ and add a single ACL for Walter:

>>> search_results = spy.search({'Name': 'Hydrocracker'})
>>> push_results = spy.acl.push(search_results, {'Username': 'walter.reed@va.com', 'Read': True})

Add multiple ACLs – one for Reed Abook (a user) and one for the Everyone group:

>>> search_results = spy.search({'Name': 'Hydrocracker'})
>>> push_results = spy.acl.push(search_results, [{
>>>                                 'Username': 'reed.abook@seeq.com',
>>>                                 'Read': True,
>>>                                 'Write': True,
>>>                                 'Manage': True
>>>                             }, {
>>>                                 'Name': 'Everyone',
>>>                                 'Type': 'UserGroup',
>>>                                 'Read': True
>>>                             }])