# -----------------------------------------------------------------------------------------# (C) Copyright IBM Corp. 2023-2025.# https://opensource.org/licenses/BSD-3-Clause# -----------------------------------------------------------------------------------------from__future__importannotationsimportjsonfromtypingimportAny,TYPE_CHECKINGfromwarningsimportwarnimportibm_watsonx_ai._wrappers.requestsasrequestsfromibm_watsonx_ai.lifecycleimportSpecStatesfromibm_watsonx_ai.metanamesimportSwSpecMetaNamesfromibm_watsonx_ai.utilsimportSW_SPEC_DETAILS_TYPEfromibm_watsonx_ai.utils.utilsimport_get_id_from_deprecated_uidfromibm_watsonx_ai.wml_client_errorimportWMLClientError,ResourceIdByNameNotFoundfromibm_watsonx_ai.wml_resourceimportWMLResourceifTYPE_CHECKING:fromibm_watsonx_aiimportAPIClientfrompandasimportDataFrame[docs]classSwSpec(WMLResource):"""Store and manage software specs."""ConfigurationMetaNames=SwSpecMetaNames()"""MetaNames for Software Specification creation."""def__init__(self,client:APIClient):WMLResource.__init__(self,__name__,client)self.software_spec_list=None[docs]defget_details(self,sw_spec_id:str|None=None,state_info:bool=False,**kwargs:Any)->dict[str,Any]:"""Get software specification details. If no sw_spec_id is passed, details for all software specifications are returned. :param sw_spec_id: ID of the software specification :type sw_spec_id: str, optional :param state_info: works only when `sw_spec_id` is None, instead of returning details of software specs, it returns the state of the software specs information (supported, unsupported, deprecated), containing suggested replacement in case of unsupported or deprecated software specs :type sw_spec_id: bool :return: metadata of the stored software specification(s) :rtype: - **dict** - if `sw_spec_uid` is not None - **{"resources": [dict]}** - if `sw_spec_uid` is None **Examples** .. code-block:: python sw_spec_details = client.software_specifications.get_details(sw_spec_uid) sw_spec_details = client.software_specifications.get_details() sw_spec_state_details = client.software_specifications.get_details(state_info=True) """sw_spec_id=_get_id_from_deprecated_uid(kwargs,sw_spec_id,"sw_spec",can_be_none=True)SwSpec._validate_type(sw_spec_id,"sw_spec_id",str,False)ifsw_spec_id:response=requests.get(self._client._href_definitions.get_sw_spec_href(sw_spec_id),params=self._client._params(skip_space_project_chk=True),headers=self._client._get_headers(),)ifresponse.status_code==200:returnself._get_required_element_from_response(self._handle_response(200,"get sw spec details",response))else:returnself._handle_response(200,"get sw spec details",response)else:ifstate_info:response=requests.get(self._client._href_definitions.get_sw_specs_href(),params=self._client._params(),headers=self._client._get_headers(),)returnself._handle_response(200,"get sw specs details",response)else:response=requests.get(self._client._href_definitions.get_sw_specs_href(),params=self._client._params(skip_space_project_chk=self._client.ICP_PLATFORM_SPACES),headers=self._client._get_headers(),)return{"resources":[self._get_required_element_from_response(x)forxinself._handle_response(200,"get sw specs details",response)["resources"]]} [docs]defstore(self,meta_props:dict)->dict:"""Create a software specification. :param meta_props: metadata of the space configuration. To see available meta names, use: .. code-block:: python client.software_specifications.ConfigurationMetaNames.get() :type meta_props: dict :return: metadata of the stored space :rtype: dict **Example:** .. code-block:: python meta_props = { client.software_specifications.ConfigurationMetaNames.NAME: "skl_pipeline_heart_problem_prediction", client.software_specifications.ConfigurationMetaNames.DESCRIPTION: "description scikit-learn_0.20", client.software_specifications.ConfigurationMetaNames.PACKAGE_EXTENSIONS: [], client.software_specifications.ConfigurationMetaNames.SOFTWARE_CONFIGURATION: {}, client.software_specifications.ConfigurationMetaNames.BASE_SOFTWARE_SPECIFICATION: {"guid": "<guid>"} } sw_spec_details = client.software_specifications.store(meta_props) """SwSpec._validate_type(meta_props,"meta_props",dict,True)sw_spec_meta=self.ConfigurationMetaNames._generate_resource_metadata(meta_props,with_validation=True,client=self._client)sw_spec_meta_json=json.dumps(sw_spec_meta)href=self._client._href_definitions.get_sw_specs_href()creation_response=requests.post(href,params=self._client._params(),headers=self._client._get_headers(),data=sw_spec_meta_json,)sw_spec_details=self._handle_response(201,"creating sofware specifications",creation_response)returnsw_spec_details [docs]deflist(self,limit:int|None=None,spec_states:list[SpecStates]|None=None)->DataFrame:"""List software specifications in a table format. :param limit: limit number of fetched records :type limit: int, optional :param spec_states: specification state filter, by default shows available, supported and custom software specifications :type spec_states: list[SpecStates], optional :return: pandas.DataFrame with listed software specifications :rtype: pandas.DataFrame **Example:** .. code-block:: python client.software_specifications.list() """ifspec_statesisNone:spec_states=[SpecStates.SUPPORTED,SpecStates.AVAILABLE,""]spec_states=[s.valueifisinstance(s,SpecStates)elsesforsinspec_states]asset_details=self.get_details(state_info=True)sw_spec_values=[(m["metadata"]["name"],m["metadata"]["asset_id"],m["entity"]["software_specification"].get("type","derived"),self._get_spec_state(m),m["metadata"].get("life_cycle",{}).get("replacement_name",""),)forminasset_details["resources"]ifself._get_spec_state(m)inspec_states]table=self._list(sw_spec_values,["NAME","ID","TYPE","STATE","REPLACEMENT"],limit,)returntable [docs]@staticmethoddefget_id(sw_spec_details:dict)->str:"""Get the unique ID of a software specification. :param sw_spec_details: metadata of the software specification :type sw_spec_details: dict :return: unique ID of the software specification :rtype: str **Example:** .. code-block:: python asset_id = client.software_specifications.get_id(sw_spec_details) """SwSpec._validate_type(sw_spec_details,"sw_spec_details",object,True)SwSpec._validate_type_of_details(sw_spec_details,SW_SPEC_DETAILS_TYPE)returnWMLResource._get_required_element_from_dict(sw_spec_details,"sw_spec_details",["metadata","asset_id"]) [docs]@staticmethoddefget_uid(sw_spec_details:dict)->str:"""Get the unique ID of a software specification. *Deprecated:* Use ``get_id(sw_spec_details)`` instead. :param sw_spec_details: metadata of the software specification :type sw_spec_details: dict :return: unique ID of the software specification :rtype: str **Example:** .. code-block:: python asset_uid = client.software_specifications.get_uid(sw_spec_details) """get_uid_method_deprecated_warning=("This method is deprecated, please use `get_id(sw_spec_details)` instead")warn(get_uid_method_deprecated_warning,category=DeprecationWarning)returnSwSpec.get_id(sw_spec_details) [docs]defget_id_by_name(self,sw_spec_name:str)->str:"""Get the unique ID of a software specification. :param sw_spec_name: name of the software specification :type sw_spec_name: str :return: unique ID of the software specification :rtype: str **Example:** .. code-block:: python asset_uid = client.software_specifications.get_id_by_name(sw_spec_name) """SwSpec._validate_type(sw_spec_name,"sw_spec_name",str,True)parameters=self._client._params(skip_space_project_chk=True)parameters.update(name=sw_spec_name)response=requests.get(self._client._href_definitions.get_sw_specs_href(),params=parameters,headers=self._client._get_headers(),)total_values=self._handle_response(200,"list assets",response)["total_results"]iftotal_values!=0:sw_spec_details=self._handle_response(200,"list assets",response)["resources"]returnsw_spec_details[0]["metadata"]["asset_id"]else:raiseResourceIdByNameNotFound(sw_spec_name,"software spec") [docs]defget_uid_by_name(self,sw_spec_name:str)->str:"""Get the unique ID of a software specification. *Deprecated:* Use ``get_id_by_name(self, sw_spec_name)`` instead. :param sw_spec_name: name of the software specification :type sw_spec_name: str :return: unique ID of the software specification :rtype: str **Example:** .. code-block:: python asset_uid = client.software_specifications.get_uid_by_name(sw_spec_name) """get_uid_by_name_method_deprecated_warning="This method is deprecated, please use `get_id_by_name(sw_spec_name)` instead"warn(get_uid_by_name_method_deprecated_warning,category=DeprecationWarning)returnSwSpec.get_id_by_name(self,sw_spec_name) [docs]@staticmethoddefget_href(sw_spec_details:dict)->str:"""Get the URL of a software specification. :param sw_spec_details: details of the software specification :type sw_spec_details: dict :return: href of the software specification :rtype: str **Example:** .. code-block:: python sw_spec_details = client.software_specifications.get_details(sw_spec_id) sw_spec_href = client.software_specifications.get_href(sw_spec_details) """SwSpec._validate_type(sw_spec_details,"sw_spec_details",object,True)SwSpec._validate_type_of_details(sw_spec_details,SW_SPEC_DETAILS_TYPE)returnWMLResource._get_required_element_from_dict(sw_spec_details,"sw_spec_details",["metadata","href"]) [docs]defdelete(self,sw_spec_id:str|None=None,**kwargs:Any)->str:"""Delete a software specification. :param sw_spec_id: unique ID of the software specification :type sw_spec_id: str :return: status ("SUCCESS" or "FAILED") :rtype: str **Example:** .. code-block:: python client.software_specifications.delete(sw_spec_id) """sw_spec_id=_get_id_from_deprecated_uid(kwargs,sw_spec_id,"sw_spec",can_be_none=False)SwSpec._validate_type(sw_spec_id,"sw_spec_id",str,True)response=requests.delete(self._client._href_definitions.get_sw_spec_href(sw_spec_id),params=self._client._params(),headers=self._client._get_headers(),)ifresponse.status_code==200:returnself._get_required_element_from_response(response.json())# type: ignoreelse:returnself._handle_response(204,"delete software specification",response) [docs]defadd_package_extension(self,sw_spec_id:str|None=None,pkg_extn_id:str|None=None,**kwargs:Any,)->str:"""Add a package extension to a software specification's existing metadata. :param sw_spec_id: unique ID of the software specification to be updated :type sw_spec_id: str :param pkg_extn_id: unique ID of the package extension to be added to the software specification :type pkg_extn_id: str :return: status :rtype: str **Example:** .. code-block:: python client.software_specifications.add_package_extension(sw_spec_id, pkg_extn_id) """ifpkg_extn_idisNone:raiseTypeError("add_package_extension() missing 1 required positional argument: 'pkg_extn_id'")sw_spec_id=_get_id_from_deprecated_uid(kwargs,sw_spec_id,"sw_spec",can_be_none=False)##For CP4D, check if either spce or project ID is setself._client._check_if_either_is_set()self._validate_type(sw_spec_id,"sw_spec_id",str,True)self._validate_type(pkg_extn_id,"pkg_extn_id",str,True)url=self._client._href_definitions.get_sw_spec_href(sw_spec_id)url=url+"/package_extensions/"+pkg_extn_idresponse=requests.put(url,params=self._client._params(),headers=self._client._get_headers())ifresponse.status_code==204:print("SUCCESS")return"SUCCESS"else:returnself._handle_response(204,"pkg spec add",response,False) [docs]defdelete_package_extension(self,sw_spec_id:str|None=None,pkg_extn_id:str|None=None,**kwargs:Any,)->str:"""Delete a package extension from a software specification's existing metadata. :param sw_spec_id: unique ID of the software specification to be updated :type sw_spec_id: str :param pkg_extn_id: unique ID of the package extension to be deleted from the software specification :type pkg_extn_id: str :return: status :rtype: str **Example:** .. code-block:: python client.software_specifications.delete_package_extension(sw_spec_uid, pkg_extn_id) """ifpkg_extn_idisNone:raiseTypeError("add_package_extension() missing 1 required positional argument: 'pkg_extn_id'")sw_spec_id=_get_id_from_deprecated_uid(kwargs,sw_spec_id,"sw_spec",can_be_none=False)##For CP4D, check if either spce or project ID is setself._client._check_if_either_is_set()self._validate_type(sw_spec_id,"sw_spec_id",str,True)self._validate_type(pkg_extn_id,"pkg_extn_id",str,True)url=self._client._href_definitions.get_sw_spec_href(sw_spec_id)url=url+"/package_extensions/"+pkg_extn_idresponse=requests.delete(url,params=self._client._params(),headers=self._client._get_headers())returnself._handle_response(204,"pkg spec delete",response,False) @staticmethoddef_get_spec_state(spec_details:dict)->str:ifspec_details["entity"].get("software_specification").get("type")!="base":return""elif"life_cycle"notinspec_details["metadata"]:return(SpecStates.SUPPORTED.value)# if no lifecycle info in the metadata, then we should assume it is supportedelifSpecStates.RETIRED.valueinspec_details["metadata"]["life_cycle"]:returnSpecStates.RETIRED.valueelifSpecStates.CONSTRICTED.valueinspec_details["metadata"]["life_cycle"]:returnSpecStates.CONSTRICTED.valueelifSpecStates.DEPRECATED.valueinspec_details["metadata"]["life_cycle"]:returnSpecStates.DEPRECATED.valueelse:forstateinSpecStates:ifstate.valueinspec_details["metadata"]["life_cycle"]:returnstate.valuereturn(SpecStates.SUPPORTED.value)# when no other info in lifecycle, then we should assume it is supporteddef_get_required_element_from_response(self,response_data:dict[str,Any])->dict:WMLResource._validate_type(response_data,"sw_spec_response",dict)try:new_el={"metadata":{"name":response_data["metadata"]["name"],"asset_id":response_data["metadata"]["asset_id"],"href":response_data["metadata"]["href"],"asset_type":response_data["metadata"]["asset_type"],"created_at":response_data["metadata"]["created_at"],},"entity":response_data["entity"],}if"life_cycle"inresponse_data["metadata"]:new_el["metadata"]["life_cycle"]=response_data["metadata"]["life_cycle"]if"href"inresponse_data["metadata"]:href_without_host=response_data["metadata"]["href"].split(".com")[-1]new_el["metadata"].update({"href":href_without_host})returnnew_elexceptException:raiseWMLClientError("Failed to read Response from down-stream service: "+str(response_data))def_get_state_info(self)->tuple[dict,dict]:spec_details=self.get_details(state_info=True)state_info_by_id={s["metadata"].get("asset_id"):{"state":self._get_spec_state(s),"replacement":s["metadata"].get("life_cycle",{}).get("replacement_name",""),}forsinspec_details["resources"]}state_info_by_name={s["metadata"].get("name"):{"state":self._get_spec_state(s),"replacement":s["metadata"].get("life_cycle",{}).get("replacement_name",""),}forsinspec_details["resources"]}returnstate_info_by_id,state_info_by_namedef_get_info(self,asset_details)->dict|None:ifnothasattr(self,"_spec_info"):self._spec_info=self._get_state_info()if(sw_spec_id:=asset_details.get("entity",{}).get("software_spec",{}).get("id"))isnotNone:returnself._spec_info[0].get(sw_spec_id)elif(sw_spec_name:=asset_details.get("entity",{}).get("software_spec",{}).get("name"))isnotNone:returnself._spec_info[1].get(sw_spec_name)def_get_state(self,asset_details)->str:spec_info=self._get_info(asset_details)ifspec_info:returnspec_info.get("state","")else:return"not_provided"def_get_replacement(self,asset_details)->str:spec_info=self._get_info(asset_details)ifspec_info:returnspec_info.get("replacement","")else:return""