Metadata-Version: 2.0
Name: dellemc-unity-sdk
Version: 1.0
Summary: Package used to create requests to DellEMC Unity.
Home-page: https://github.com/ansible-dellemc-unity/dellemc-unity-sdk
Author: ansible-dellemc-unity
Author-email: mityushin.dmitry@gmail.com
License: UNKNOWN
Platform: UNKNOWN
Classifier: Programming Language :: Python
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Dist: dellemc-unity-sdk

# Readme

A python module to execute [ansible-dellemc-unity](https://github.com/ansible-dellemc-unity/ansible-dellemc-unity) (Ansible modules for DellEMC Unity).

This SDK provides common functions for all Ansible modules and special interface to communicate with Unity.

## How to install this SDK

You have several ways to install this SDK

##### Install from pip repo
``pip install dellemc-unity-sdk``

##### Install from source

    git clone https://github.com/ansible-dellemc-unity/dellemc-unity-sdk.git
    cd dellemc-unity-sdk
    python setup.py sdist
    sudo pip install dist/dellemc_unity_sdk.xxxx.tar.gz

##### Install from source var2

    git clone https://github.com/ansible-dellemc-unity/dellemc-unity-sdk.git
    cd dellemc-unity-sdk
    python setup.py sdist bdist_wheel
    sudo pip install dist/dellemc_unity_sdk-XXXX-pyY-none-any.whl  

## How to write modules

According to our experience and [issue #4](https://github.com/ansible-dellemc-unity/dellemc-unity-sdk/issues/4) , 
you should create an instance of AnsibleModule in your module. So to create you should argument_spec use:

``supportive_functions.create_arguments_for_ansible_module(array_of_dictionaries)`` or 
``supportive_functions.create_arguments_for_ansible_module(template)``

After that make an instance of AnsibleModule and put it next to template into

``runner.run(ansible_module, template)``

Your module will be automatically executed by SDK.

## How to write templates for runner.run(...)

template is a dictionary that should have following keys:

1. ``constants.REST_OBJECT = 'rest_object'`` value of this key should be a REST object
2. ``constants.ACTIONS = 'actions'`` value of this key should be a dictionary of actions,
for example, {'create:{...}', 'delete':{...},...}

To execute actions automatically dictionary of action should have following parameters:

1. ``constants.ACTION_TYPE`` value of this key should be ``constants.ActionType.UPDATE`` or ``constants.ActionType.QUERY``
2. ``constants.PARAMETER_TYPES = 'parameter_types'`` value of this key should be a dictionary that should have keys:
'required' and 'optional' and value of each key should be iterable.

For example:

    {
        constants.REST_OBJECT: 'pool',
        constants.ACTIONS: {
            'delete':
                {constants.ACTION_TYPE: constants.ActionType.UPDATE,
                 constants.PARAMETER_TYPES: parameters_all.get('delete')}
        }
    }

### Optional parameters (keys) for template

1. ``constants.REST_OBJECT_FOR_GET_REQUEST`` use this key for making GET request to REST
 object that is different from ``constants.REST_OBJECT``

### Optional parameters (keys) for dictionary of actions

1. ``constants.DO_ACTION = 'do action'`` use this constant if you want the parameter name in the playbook to 
be different from the one in the REST model. For example,

       {
           constants.REST_OBJECT: 'lun',
           constants.ACTIONS: {
               'create':
                   {
                      constants.ACTION_TYPE: constants.ActionType.UPDATE,
                      constants.PARAMETER_TYPES: parameters_all.get('create'),
                      constants.DO_ACTION: "
                   }
           }
       }    

### How to write type of parameters for validator

It should be a dictionary that can be written in two ways

#### Option with type of arguments

    {
        "required_argument_var1" : dict(required=True, type=<type of this object>, default=<default_value>),
        "required_argument_var2" : dict(required=True),
        "optional_argument": dict(required=False),
        "optional_argument_var_2": dict()... 
    }

you can skip some keys in dictionary, by default it will be 
``dict(required=False, type=None, default=None)``

**supported types of arguments**:

* _None_ - validator doesn't check type of this argument
* _dict_ - validator expect type dictionary
* _object_ - same as dict
* _bool_
* _int_
* _str_
* _list_
* any others python's object
* supported enums from dellemc_unity_sdk.rest_supported_enums

#### Option with keys (easy way)

Dictionary should have keys: "required" and "optional". For example: 

    {
        'required': {'type', 'name'},
        'optional': {'description','osType','tenant'},
    }

## How to execute custom functions

If your request can't be made by functions ``runner.do_update_request(...)`` or ``runner.do_query_request(...)`` you can
execute your own function by using key ``constants.EXECUTED_BY = 'executed_by'``

For example:

    {
        constants.REST_OBJECT: 'pool',
        constants.ACTIONS: {'create': {constants.EXECUTED_BY: function}}
    }

Your function should have 2 parameters (parameters, unity). parameters = parameters from *.yml file, 
unity = instance of class Unity and also function must have return statement, 
that will be add to output in parameter ``'output'``

## Additional information

All REST objects have action _"get"_ (``constants.GET``), that sends GET requests, you are allowed to redefine this action 




