.. code:: ipython3

    from seeq import spy
    import pandas as pd
    
    # Set the compatibility option so that you maximize the chance that SPy will remain compatible with your notebook/script
    spy.options.compatibility = 192

.. code:: ipython3

    # Log into Seeq Server if you're not using Seeq Data Lab:
    spy.login(url='http://localhost:34216', credentials_file='../credentials.key', force=False)

spy.acl
=======

Retrieves and modifies access control configuration for signals,
conditions, scalars, metrics, workbooks, assets or any other item in
Seeq that supports access control.

*ACL* is an acronym for *Access Control List*, which is a simple list of
users and user groups that have *Read*, *Write* and/or *Manage* access
for an item. Access control is often hierarchical in nature, with leaf
nodes of an asset tree or workbooks within a folder inheriting the
access control of their parent.

Modifying ACLs for Pushed Data
------------------------------

In the following example, we will push some data and then modify the
ACLs for that data.

.. code:: ipython3

    import csv
    csv_file = pd.read_csv('Support Files/csv_import_example.csv', parse_dates=['TIME(unitless)'], index_col='TIME(unitless)')
    csv_file.head()

.. code:: ipython3

    push_results = spy.push(data=csv_file, workbook='SPy Documentation Examples >> spy.acl')
    push_results

After pushing, we can use the returned DataFrame (``push_results``) to
modify the ACLs:

.. code:: ipython3

    # This will remove the Everyone group by replacing with only me
    spy.acl.push(push_results, {
        'ID': spy.user.id,
        'Read': True,
        'Write': True,
        'Manage': True
    }, replace=True, disable_inheritance=True)

Modifying ACLs for Pushed Workbooks
-----------------------------------

You can also modify the access control for the workbook that was
created:

.. code:: ipython3

    spy.acl.push(push_results.spy.workbook_id, {
        'ID': spy.user.id,
        'Read': True,
        'Write': True,
        'Manage': True
    }, replace=True, disable_inheritance=True)

Alternatively, you can search for workbooks and modify them that way:

.. code:: ipython3

    workbooks = spy.workbooks.search({'Name': 'spy.acl', 'Path': 'SPy Documentation Examples'})
    spy.acl.push(workbooks, {
        'Name': 'Everyone',
        'Read': True,
        'Write': True,
        'Manage': False
    })

Retrieving ACLs
---------------

You can use the same approach to retrieve ACLs for a set of items:

.. code:: ipython3

    pull_acl_df = spy.acl.pull(push_results)
    pull_acl_df

Each entry in the table now has an ``Access Control`` column, and each
cell in that column is an embedded DataFrame you can access like so:

.. code:: ipython3

    acl_df = pull_acl_df.at['BITDEP(ft)', 'Access Control']
    acl_df

Detailed Help
-------------

All SPy functions have detailed documentation to help you use them. Just
execute ``help(spy.<func>)`` like you see below.

.. code:: ipython3

    help(spy.acl)

API Reference Links
-------------------

- :py:mod:`seeq.spy.acl`