ed f string format and added documentation

Author: ashviniwaghmode

recipes/python/backup-restore/README.md

@@ -3,13 +3,15 @@
 ## Executing the scripts:
 
 Pre-requisites:
-- NetBackup 8.2.1(Build 209 or higher) or higher      
-- Python 3.5 or higher
+- NetBackup 8.2.1 or higher      
+- Python 3.6 or higher
 - Python modules: `requests`
 
 Use the following commands to run the scripts.
 ### - Single VM backup and restore
 
+This single_vm_backup_restore.py script describes how to backup VM using protection plan and restore the single VMware virtual machine that were backuped with NetBackup for VMware.
+
 `python single_vm_backup_restore.py --master_server <master_server> --master_username <master_username> --master_password <master_password> --vcenter_name <vcenter_name> --vcenter_username <vcenter_username> --vcenter_password <vcenter_password> --protection_plan_name <protection_plan_name> --clientvm <client_vm_name> --restore_vmname <restore_vm_name>`
 
 All parameters can also be passed as command line arguments.
@@ -29,7 +31,7 @@ usage: single_vm_backup_restore.py [-h] [--master_server MASTER_SERVER]
 
 Single VM backup and restore scenario
 
-optional arguments:
+Arguments:
   -h, --help            show this help message and exit
   --master_server MASTER_SERVER
                         NetBackup master server name
@@ -67,6 +69,8 @@ Execution flow of single VM backup and restore script:
 
 ### - Group VM backup and restore
 
+This group_vm_backup_restore.py script describes how to backup multiple VMs using protection plan and perform bulk restore of VMware virtual machines that were backuped with NetBackup for VMware.
+
 `python group_vm_backup_restore.py --master_server <master_server> --master_username <master_username> --master_password <master_password> --vcenter_name <vcenter_name> --vcenter_username <vcenter_username> --vcenter_password <vcenter_password> --protection_plan_name <protection_plan_name> --querystring <Query_string> --vip_group_name <group_name> --restore_vmname_prefix <restore_vmname_prefix>`
 
 All parameters can also be passed as command line arguments.
@@ -87,7 +91,7 @@ usage: group_vm_backup_restore.py [-h] [--master_server MASTER_SERVER]
 
 Group VM backup and restore scenario
 
-optional arguments:
+Arguments:
   -h, --help            show this help message and exit
   --master_server MASTER_SERVER
                         NetBackup master server

recipes/python/backup-restore/common.py

@@ -1,8 +1,8 @@
-## The library contain common functions which are used for both single and group VM backup and restore.
+""" The library contain common functions which are used for both single and group VM backup and restore. """
 
-## The script can be run with Python 3.5 or higher version. 
+## The script can be run with Python 3.6 or higher version.
 
-## The script requires 'requests' library to make the API calls. The library can be installed using the command: pip install requests.
+## The script requires 'requests' library to make the API calls.
 
 import json
 import os
@@ -12,97 +12,110 @@
 
 headers = {"Content-Type" : "application/vnd.netbackup+json;version=4.0"}
 
-# Get the base netbackup url
+# Get the base NetBackup url
 def get_nbu_base_url(host, port):
+    """ This function return NetBackup base url """
     port = f":{str(port)}" if port else ''
     baseurl = f"https://{host}{port}/netbackup/"
     return baseurl
 
-# Login to the netbackup and get the authorization token
+# Login to the NetBackup and get the authorization token
 def get_authenticate_token(baseurl, username, password):
+    """ This function return token of NB master server """
     creds = {'userName':username, 'password':password}
-    url = baseurl + 'login'
+    url = f"{baseurl}login"
     status_code, response_text = rest_request('POST', url, headers, data=creds)
     validate_response(status_code, 201, response_text)
     token = response_text['token']
     return token
 
 # Add vCenter credential
 def add_vcenter_credential(baseurl, token, vcenter_server, vcenter_username, vcenter_password, vcenter_port, vcenter_server_type):
-    print(f"Add the vcenter credential:[{vcenter_server}]")
-    headers.update({'Authorization': token}) 
-    url = baseurl + 'config/servers/vmservers'
-    payload = {'serverName':vcenter_server, 'vmType':vcenter_server_type, 'userId':vcenter_username, 'password':vcenter_password, 'port':vcenter_port}
+    """ This function add the vCenter into NBU master server """
+    print(f"Add the vCenter credential:[{vcenter_server}]")
+    headers.update({'Authorization': token})
+    url = f"{baseurl}config/servers/vmservers"
+    payload = {'serverName':vcenter_server, 'vmType':vcenter_server_type, 'userId':vcenter_username,\
+                    'password':vcenter_password, 'port':vcenter_port}
     status_code, response_text = rest_request('POST', url, headers, data=payload)
     validate_response(status_code, 201, response_text)
-    print(f"Vcenter credentials added successfully:[{vcenter_server}]")
+    print(f"vCenter credentials added successfully:[{vcenter_server}]")
 
 # Get Vmware server discovery status
 def get_vmware_discovery_status(baseurl, token, workload_type, vcenter_server):
+    """ This function return the discovery status of vCenter server """
     headers.update({'Authorization': token})
-    url = baseurl + "admin/discovery/workloads/" + workload_type + "/status?filter=serverName eq '" + vcenter_server + "'"
+    url = f"{baseurl}admin/discovery/workloads/{workload_type}/status?"\
+                f"filter=serverName eq '{vcenter_server}'"
     status_code, response_text = rest_request('GET', url, headers)
     validate_response(status_code, 200, response_text)
     discovery_status = response_text['data'][0]['attributes']['discoveryStatus']
     return discovery_status
 
-# Get Vmware server discovery status
+# Verify Vmware server discovery status
 def verify_vmware_discovery_status(baseurl, token, workload_type, vcenter_server, timeout=600):
-    print(f"Wait for Vcenter Discovery :[{vcenter_server}]")
+    """ This function verify the 'SUCESS' discovery status of vCenter """
+    print(f"Wait for vCenter Discovery :[{vcenter_server}]")
     discovery_status = ''
     end_time = time.time() + timeout
     while time.time() < end_time:
         time.sleep(30)
         discovery_status = get_vmware_discovery_status(baseurl, token, workload_type, vcenter_server)
         if discovery_status == 'SUCCESS':
-            print(f"Vcenter added successfully:[{vcenter_server}]")
+            print(f"vCenter added successfully:[{vcenter_server}]")
             break
     else:
-        print(f"Failed to verify VCenter:[{vcenter_server}] discovery with status:[{discovery_status}]")
+        print(f"Failed to verify vCenter:[{vcenter_server}] discovery with status:[{discovery_status}]")
         sys.exit(1)
-    print(f"Vcenter discovery successful:[{vcenter_server}] with status:[{discovery_status}]")
+    print(f"vCenter discovery successful:[{vcenter_server}] with status:[{discovery_status}]")
 
 # Get asset info
 def get_asset_info(baseurl, token, workload_type, client):
+    """ This function return the asset info """
     print(f"Get client asset info:[{client}]")
     headers.update({'Authorization': token})
-    url = baseurl + "asset-service/workloads/" + workload_type + "/assets?filter=commonAssetAttributes/displayName eq '" + client + "'"
+    url = f"{baseurl}asset-service/workloads/{workload_type}/assets?"\
+                f"filter=commonAssetAttributes/displayName eq '{client}'"
     status_code, response_text = rest_request('GET', url, headers)
     validate_response(status_code, 200, response_text)
+
     asset_id = response_text['data'][0]['id']
     uuid = response_text['data'][0]['attributes']['instanceUuid']
     exsi_host = response_text['data'][0]['attributes']['host']
+
     print(f"Client asset Id:[{asset_id}]")
     print(f"Client uuid Id:[{uuid}]")
     print(f"Client exsi host:[{exsi_host}]")
     return asset_id, uuid, exsi_host
 
 # Get StorageUnits
 def get_storage_units(baseurl, token):
+    """ This function return the storage unit name """
     headers.update({'Authorization': token})
-    url = baseurl + "storage/storage-units"
+    url = f"{baseurl}storage/storage-units"
     status_code, response_text = rest_request('GET', url, headers)
     validate_response(status_code, 200, response_text)
     storage_unit_name = response_text['data'][0]['id']
     is_instant_access_enable = response_text['data'][0]['attributes']['instantAccessEnabled']
+
     if is_instant_access_enable:
         print(f"Storage unit:[{storage_unit_name}] enabled for instant access")
-        return storage_unit_name
     else:
         print(f"Storage unit:[{storage_unit_name}] disable for instant access")
         raise Exception(f"Storage unit:[{storage_unit_name}] disabled for instant access")
+    return storage_unit_name
 
 # Create protection plan
 def create_protection_plan(baseurl, token, protection_plan_name, storage_unit_name):
+    """ This function create the protection plan """
     print(f"Create protection plan:[{protection_plan_name}]")
     headers.update({'Authorization': token})
-    payload = {}
-    url = baseurl + 'servicecatalog/slos?meta=accessControlId'
+    url = f"{baseurl}servicecatalog/slos?meta=accessControlId"
 
     cur_dir = os.path.dirname(os.path.abspath(__file__))
     file_name = os.path.join(cur_dir, "create_protection_plan_template.json")
-    f = open(file_name)
-    data = json.load(f)
+    file_handle = open(file_name)
+    data = json.load(file_handle)
     data['data']['attributes']['name'] = protection_plan_name
     data['data']['attributes']['policyNamePrefix'] = protection_plan_name
     data['data']['attributes']['schedules'][0]['backupStorageUnit'] = storage_unit_name
@@ -115,12 +128,14 @@ def create_protection_plan(baseurl, token, protection_plan_name, storage_unit_na
     return protection_plan_id
 
 # Subscription asset to SLO
-def subscription_asset_to_slo(baseurl, token, protection_plan_id, asset_id, is_vm_group = 0):
+def subscription_asset_to_slo(baseurl, token, protection_plan_id, asset_id, is_vm_group=0):
+    """ This function subscribe the asset/group asset to protection plan """
     print(f"Subscribe client to protection plan id: [{protection_plan_id}]")
     headers.update({'Authorization': token})
-    url = baseurl + "servicecatalog/slos/" + protection_plan_id + "/subscriptions"
+    url = f"{baseurl}servicecatalog/slos/{protection_plan_id}/subscriptions"
     selection_type = "ASSETGROUP" if is_vm_group else "ASSET"
-    payload = {"data": {"type": "subscription","attributes": {"selectionType": selection_type,"selectionId": asset_id}}}
+    payload = {"data": {"type": "subscription", "attributes": \
+                {"selectionType": selection_type, "selectionId": asset_id}}}
     status_code, response_text = rest_request('POST', url, headers, data=payload)
     validate_response(status_code, 201, response_text)
     subscription_id = response_text['data']['id']
@@ -130,22 +145,25 @@ def subscription_asset_to_slo(baseurl, token, protection_plan_id, asset_id, is_v
 
 # Get subscription
 def get_subscription(baseurl, token, protection_plan_id, subscription_id):
+    """ This function return the subscription info """
     headers.update({'Authorization': token})
-    url = baseurl + "servicecatalog/slos/" + protection_plan_id + "/subscriptions/" + subscription_id
+    url = f"{baseurl}servicecatalog/slos/{protection_plan_id}/subscriptions/{subscription_id}"
     status_code, response_text = rest_request('GET', url, headers)
     validate_response(status_code, 200, response_text)
     print(f"Sucessfully fetched the subscription:[{subscription_id}] details.")
-    
+
 # Get job details
 def get_job_details(baseurl, token, jobid):
+    """ This function return the job details """
     headers.update({'Authorization': token})
-    url = baseurl + "admin/jobs/" + str(jobid)
+    url = f"{baseurl}admin/jobs/{str(jobid)}"
     status_code, response_text = rest_request('GET', url, headers)
     validate_response(status_code, 200, response_text)
     return response_text
 
 # Verify given job state and status
 def verify_job_state(baseurl, token, jobid, expected_state, expected_status=0, timeout=1200):
+    """ This function verify the job status and state with expected status and state """
     if jobid:
         print(f"Wait for backup job to complete. Backup jobid:[{jobid}]")
         # Verify backup job status
@@ -158,7 +176,7 @@ def verify_job_state(baseurl, token, jobid, expected_state, expected_status=0, t
                 print(f"Job:[{jobid}] completed with expected state:[{expected_state}]")
                 status = response_text['data']['attributes']['status']
                 print(f"Actual status:[{status}] and expected status:[{expected_status}]")
-                if status == expected_status or status == 1:
+                if status == expected_status:
                     print(f"Job:[{jobid}] completed with expected status:[{expected_status}]")
                     break
                 else:
@@ -168,37 +186,40 @@ def verify_job_state(baseurl, token, jobid, expected_state, expected_status=0, t
             print(f"Failed backup jobid:[{jobid}] with state:[{state}]")
             raise Exception(f"Failed backup jobid:[{jobid}] with state:[{state}]")
 
-
-
 # Remove protection plan
 def remove_protectionplan(baseurl, token, protection_plan_id):
+    """ This function remove the given protection plan """
     if protection_plan_id:
         headers.update({'Authorization': token})
-        url = baseurl + 'servicecatalog/slos/' +protection_plan_id
+        url = f"{baseurl}servicecatalog/slos/{protection_plan_id}"
         status_code, response_text = rest_request('DELETE', url, headers)
-        validate_response(status_code, 204, response_text) 
+        validate_response(status_code, 204, response_text)
         print(f"Successfully removed protection plan:[{protection_plan_id}]")
 
 # Remove vm subscription from protection plan
 def remove_subscription(baseurl, token, protection_plan_id, subscription_id):
+    """ This function remove subscription from protection plan """
     if protection_plan_id and subscription_id:
         headers.update({'Authorization': token})
-        url = baseurl + 'servicecatalog/slos/' +protection_plan_id+ '/subscriptions/' +subscription_id
+        url = f"{baseurl}servicecatalog/slos/{protection_plan_id}/subscriptions/{subscription_id}"
         status_code, response_text = rest_request('DELETE', url, headers)
-        validate_response(status_code, 204, response_text)  
-        print(f"Successfully removed asset subscription:[{subscription_id}] from protection plan:[{protection_plan_id}]")
+        validate_response(status_code, 204, response_text)
+        print(f"Successfully removed asset subscription:[{subscription_id}] "\
+                f"from protection plan:[{protection_plan_id}]")
 
-# Remove vcenter creds from netbackup master
+# Remove vCenter creds from NetBackup master
 def remove_vcenter_creds(baseurl, token, vcenter_name):
+    """ This function remove the vCenter from NBU master """
     if vcenter_name:
         headers.update({'Authorization': token})
-        url = baseurl + 'config/servers/vmservers/' +vcenter_name
+        url = f"{baseurl}config/servers/vmservers/{vcenter_name}"
         status_code, response_text = rest_request('DELETE', url, headers)
         validate_response(status_code, 204, response_text)
-        print(f"Successfully removed vcenter:[{vcenter_name}] credential")
+        print(f"Successfully removed vCenter:[{vcenter_name}] from NBU master")
 
 # Execute REST API request
 def rest_request(request_type, uri, header=None, **kwargs):
+    """ This function make call to the REST API """
     session = requests.session()
     payload = kwargs.get('data')
     if request_type == 'POST':
@@ -233,17 +254,18 @@ def rest_request(request_type, uri, header=None, **kwargs):
     except json.decoder.JSONDecodeError:
         print(f"Could not parse json from [{response_text}]")
 
-    print(f"Sucessfully sent REST request:[{uri}]")
+    print(f"Successfully sent REST request:[{uri}]")
     print(f"Status code:[{response.status_code}]")
     print(f"Response text:[{response.text}]")
     return response.status_code, response_text
 
+# Validate the response code of the request
 def validate_response(actual_status_code, expected_status_code, response_text):
-    # Validate the response code of the request
-    if(actual_status_code == expected_status_code):
-        print(f"Sucessfully validate the response status code:[{expected_status_code}]")
-        return True
+    """ This function validate the response status code with expected response code """
+    if actual_status_code == expected_status_code:
+        print(f"Successfully validate the response status code:[{expected_status_code}]")
     else:
-        print(f"Actual status code:[{actual_status_code}] not match with expected status code:[{expected_status_code}]")
-        raise Exception(f"Response Error:[{response_text['errorMessage']}] and details:[{response_text['errorDetails']}]")
-        return False
+        print(f"Actual status code:[{actual_status_code}] not match "\
+                f"with expected status code:[{expected_status_code}]")
+        raise Exception(f"Response Error:[{response_text['errorMessage']}] and "\
+                            f"details:[{response_text['errorDetails']}]")