catalystwan 0.41.2__py3-none-any.whl → 0.41.2.dev0__py3-none-any.whl

catalystwan/api/builders/feature_profiles/uc_voice.py

@@ -0,0 +1,287 @@
+# Copyright 2024 Cisco Systems, Inc. and its affiliates
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Dict, List, Optional, Union
+from uuid import UUID
+
+from catalystwan.api.builders.feature_profiles.report import FeatureProfileBuildReport, handle_create_parcel
+from catalystwan.api.configuration_groups.parcel import as_default
+from catalystwan.api.feature_profile_api import UcVoiceFeatureProfileAPI
+from catalystwan.endpoints.configuration.feature_profile.sdwan.uc_voice import UcVoiceFeatureProfile
+from catalystwan.models.configuration.feature_profile.common import FeatureProfileCreationPayload, RefIdItem
+from catalystwan.models.configuration.feature_profile.sdwan.uc_voice import (
+    AnalogInterfaceParcel,
+    AnyUcVoiceParcel,
+    CallRoutingParcel,
+    DigitalInterfaceParcel,
+    MediaProfileParcel,
+    ServerGroupParcel,
+    SrstParcel,
+    TranslationProfileParcel,
+    TranslationRuleParcel,
+    TrunkGroupParcel,
+    VoiceGlobalParcel,
+    VoiceTenantParcel,
+)
+from catalystwan.models.configuration.feature_profile.sdwan.uc_voice.analog_interface import (
+    Association as AnalogInterfaceAssociation,
+)
+from catalystwan.models.configuration.feature_profile.sdwan.uc_voice.call_routing import (
+    Association as CallRoutingAssociation,
+)
+from catalystwan.models.configuration.feature_profile.sdwan.uc_voice.digital_interface import (
+    Association as DigitalInterfaceAssociation,
+)
+from catalystwan.models.configuration.feature_profile.sdwan.uc_voice.srst import Association as SrstAssociation
+from catalystwan.models.configuration.feature_profile.sdwan.uc_voice.translation_profile import CallType
+
+logger = logging.getLogger(__name__)
+
+if TYPE_CHECKING:
+    from catalystwan.session import ManagerSession
+
+
+ParcelWithAssociations = Union[CallRoutingParcel, DigitalInterfaceParcel, AnalogInterfaceParcel, SrstParcel]
+Association = Union[
+    List[DigitalInterfaceAssociation],
+    List[AnalogInterfaceAssociation],
+    List[CallRoutingAssociation],
+    List[SrstAssociation],
+]
+AssociableParcel = Union[
+    MediaProfileParcel,
+    ServerGroupParcel,
+    SrstParcel,
+    TranslationProfileParcel,
+    TranslationRuleParcel,
+    TrunkGroupParcel,
+    VoiceGlobalParcel,
+    VoiceTenantParcel,
+]
+
+
+@dataclass
+class TranslationProfile:
+    tpp: TranslationProfileParcel
+    calling: Optional[TranslationRuleParcel] = None
+    called: Optional[TranslationRuleParcel] = None
+
+
+def is_uuid(uuid: Optional[Union[str, UUID]]) -> bool:
+    if isinstance(uuid, UUID) or uuid is None:
+        return True
+    try:
+        UUID(uuid)
+        return True
+    except ValueError:
+        return False
+
+
+class UcVoiceFeatureProfileBuilder:
+    """
+    A class for building UC Voice feature profiles with a modular approach.
+
+    This class provides methods to construct, associate, and manage various parcels and
+    configurations required for UC Voice feature profiles.
+    """
+
+    ASSOCIABLE_PARCELS = (
+        MediaProfileParcel,
+        ServerGroupParcel,
+        SrstParcel,
+        TranslationProfileParcel,
+        TranslationRuleParcel,
+        TrunkGroupParcel,
+        VoiceGlobalParcel,
+        VoiceTenantParcel,
+    )
+
+    ASSOCIATON_FIELDS = {
+        "media_profile",
+        "server_group",
+        "translation_profile",
+        "trunk_group",
+        "voice_tenant",
+        "supervisory_disconnect",
+    }
+
+    def __init__(self, session: ManagerSession) -> None:
+        """
+        Initializes a new instance of the UC Voice Feature Profile Builder.
+
+        Args:
+            session (ManagerSession): The session object used for API communication.
+        """
+        self._profile: FeatureProfileCreationPayload
+        self._api = UcVoiceFeatureProfileAPI(session)
+        self._endpoints = UcVoiceFeatureProfile(session)
+        self._independent_parcels: List[AnyUcVoiceParcel] = []
+        self._associable_parcles: List[AssociableParcel] = []
+        self._translation_profiles: Dict[str, TranslationProfile] = dict()
+        self._pushed_associable_parcels: Dict[str, UUID] = {}  # Maps parcel names to their created UUIDs.
+        self._parcels_with_associations: List[ParcelWithAssociations] = []
+
+    def add_profile_name_and_description(self, feature_profile: FeatureProfileCreationPayload) -> None:
+        """
+        Adds a name and description to the feature profile being built.
+
+        Args:
+            feature_profile (FeatureProfileCreationPayload): The feature profile payload containing
+                the name and description.
+        """
+        self._profile = feature_profile
+
+    def add_independent_parcel(self, parcel: AnyUcVoiceParcel) -> None:
+        """
+        Adds an independent parcel to the feature profile.
+
+        Args:
+            parcel (AnyUcVoiceParcel): The parcel to be added. Parcels are independent configurations
+                that do not require associations with other parcels.
+        """
+        self._independent_parcels.append(parcel)
+
+    def add_associable_parcel(self, parcel: AssociableParcel) -> None:
+        self._associable_parcles.append(parcel)
+
+    def add_translation_profile(
+        self,
+        tpp: TranslationProfileParcel,
+        calling: Optional[TranslationRuleParcel] = None,
+        called: Optional[TranslationRuleParcel] = None,
+    ) -> None:
+        """
+        Adds a translation profile to the feature profile.
+
+        Args:
+            tpp (TranslationProfileParcel): The main translation profile parcel.
+            calling (Optional[TranslationRuleParcel]): The calling rule parcel. Optional.
+            called (Optional[TranslationRuleParcel]): The called rule parcel. Optional.
+
+        Raises:
+            ValueError: If neither a calling nor a called rule is provided.
+        """
+        if not calling and not called:
+            raise ValueError("There must be at least one translation rule to create a translation profile.")
+        if tpp.parcel_name in self._translation_profiles:
+            logger.warning(f"Translation profile {tpp.parcel_name} was already added.")
+        else:
+            self._translation_profiles[tpp.parcel_name] = TranslationProfile(tpp=tpp, called=called, calling=calling)
+
+    def add_parcel_with_associations(self, parcel: ParcelWithAssociations) -> None:
+        """
+        Adds a parcel with associations to the feature profile.
+
+        Args:
+            parcel (ParcelWithAssociations): A parcel that includes associations with other entities.
+                Associations are relationships between parcels and other resources.
+        """
+        self._parcels_with_associations.append(parcel)
+
+    def build(self) -> FeatureProfileBuildReport:
+        """
+        Builds the complete UC Voice feature profile.
+
+        This method creates the feature profile on the system and processes all added parcels
+        and translation profiles, resolving associations as needed.
+
+        Returns:
+            FeatureProfileBuildReport: A report containing the details of the created feature profile.
+        """
+        profile_uuid = self._endpoints.create_uc_voice_feature_profile(self._profile).id
+        self.build_report = FeatureProfileBuildReport(profile_uuid=profile_uuid, profile_name=self._profile.name)
+
+        # Create independent parcels
+        for ip in self._independent_parcels:
+            self._create_parcel(profile_uuid, ip)
+
+        # Create translation profiles
+        for _, tp in self._translation_profiles.items():
+            tp_parcel_uuid = self._create_translation_profile(profile_uuid, tp)
+            if tp_parcel_uuid:
+                self._pushed_associable_parcels[tp.tpp.parcel_name] = tp_parcel_uuid
+
+        for ap in self._associable_parcles:
+            ap_parcel_uuid = self._create_parcel(profile_uuid, ap)
+            if ap_parcel_uuid:
+                self._pushed_associable_parcels[ap.parcel_name] = ap_parcel_uuid
+
+        # Create parcels with associations
+        for pwa in self._parcels_with_associations:
+            if pwa.association:
+                self._populate_association(pwa.association)
+            self._create_parcel(profile_uuid, pwa)
+
+        return self.build_report
+
+    @handle_create_parcel
+    def _create_parcel(self, profile_uuid: UUID, parcel: AnyUcVoiceParcel) -> UUID:
+        """
+        Internal method to create a parcel.
+
+        Args:
+            profile_uuid (UUID): The UUID of the feature profile being built.
+            parcel (AnyUcVoiceParcel): The parcel to create.
+
+        Returns:
+            UUID: The UUID of the created parcel.
+        """
+        return self._api.create_parcel(profile_uuid, parcel).id
+
+    def _create_translation_profile(self, profile_uuid: UUID, tp: TranslationProfile) -> UUID:
+        """
+        Internal method to create a translation profile.
+
+        Args:
+            profile_uuid (UUID): The UUID of the feature profile being built.
+            tp (TranslationProfile): The translation profile to create.
+
+        Returns:
+            UUID: The UUID of the created translation profile parcel.
+        """
+
+        def process_parcel(parcel: Optional[TranslationRuleParcel], parcel_type: CallType):
+            if not parcel:
+                return
+            parcel_name = parcel.parcel_name
+            if parcel_name in self._pushed_associable_parcels:
+                logger.debug(f"Translation rule {parcel_name} was already referenced in other profile.")
+                tp.tpp.set_ref_by_call_type(self._pushed_associable_parcels[parcel_name], parcel_type)
+            else:
+                parcel_uuid = self._create_parcel(profile_uuid, parcel)
+                if parcel_uuid:
+                    tp.tpp.set_ref_by_call_type(parcel_uuid, parcel_type)
+                    self._pushed_associable_parcels[parcel_name] = parcel_uuid
+
+        process_parcel(tp.called, "called")
+        process_parcel(tp.calling, "calling")
+
+        return self._create_parcel(profile_uuid, tp.tpp)
+
+    def _populate_association(self, association: Association) -> None:
+        """
+        Resolves associations for a parcel.
+
+        Updates references in the parcel's associations to use the actual UUIDs of previously
+        created parcels.
+
+        Args:
+            association (Association): A list of associations to resolve.
+        """
+        for model in association:
+            for field_name in self.ASSOCIATON_FIELDS.intersection(model.model_fields_set):
+                attr = getattr(model, field_name)
+                if isinstance(attr, RefIdItem):
+                    if is_uuid(attr.ref_id.value) or attr.ref_id.value is None:
+                        continue
+                    resolved_uuid = self._pushed_associable_parcels.get(attr.ref_id.value)
+                    if resolved_uuid:
+                        attr.ref_id.value = str(resolved_uuid)
+                    else:
+                        logger.warning(
+                            f"Unresolved reference in field '{field_name}' with value '{attr.ref_id.value}' "
+                            f"for model '{model.__class__.__name__}'. Setting to Default[None]."
+                        )
+                        attr.ref_id = as_default(None)

catalystwan/api/config_group_api.py

@@ -2,12 +2,16 @@
 
 from __future__ import annotations
 
-from typing import TYPE_CHECKING
+from typing import TYPE_CHECKING, Any, Optional, overload
+from uuid import UUID
+
+from catalystwan.typed_list import DataSequence
 
 if TYPE_CHECKING:
     from catalystwan.session import ManagerSession
 
 from catalystwan.endpoints.configuration_group import (
+    ConfigGroup,
     ConfigGroupAssociatePayload,
     ConfigGroupCreationPayload,
     ConfigGroupCreationResponse,
@@ -16,7 +20,6 @@ from catalystwan.endpoints.configuration_group import (
     ConfigGroupDisassociateResponse,
     ConfigGroupEditPayload,
     ConfigGroupEditResponse,
-    ConfigGroupResponsePayload,
     ConfigGroupVariablesCreatePayload,
     ConfigGroupVariablesCreateResponse,
     ConfigGroupVariablesEditPayload,
@@ -29,8 +32,8 @@ from catalystwan.endpoints.configuration_group import (
 
 class ConfigGroupAPI:
     def __init__(self, session: ManagerSession):
-        self.session = session
-        self.endpoint = ConfigurationGroup(session)
+        self._session = session
+        self._endpoints = ConfigurationGroup(session)
 
     def associate(self, cg_id: str, device_ids: list) -> None:
         """
@@ -43,7 +46,7 @@ class ConfigGroupAPI:
 
         payload = ConfigGroupAssociatePayload(devices=devices)
 
-        self.endpoint.associate(config_group_id=cg_id, payload=payload)
+        self._endpoints.associate(config_group_id=cg_id, payload=payload)
 
     def create(self, name: str, description: str, solution: Solution, profile_ids: list) -> ConfigGroupCreationResponse:
         """
@@ -57,7 +60,7 @@ class ConfigGroupAPI:
             name=name, description=description, solution=solution, profiles=profiles
         )
 
-        return self.endpoint.create_config_group(cg_payload)
+        return self._endpoints.create_config_group(cg_payload)
 
     def create_variables(
         self, cg_id: str, device_ids: list, suggestions: bool = True
@@ -66,13 +69,13 @@ class ConfigGroupAPI:
         Creates device specific variable data in given config-group
         """
         payload = ConfigGroupVariablesCreatePayload(deviceIds=device_ids, suggestions=suggestions)
-        return self.endpoint.create_variables(config_group_id=cg_id, payload=payload)
+        return self._endpoints.create_variables(config_group_id=cg_id, payload=payload)
 
-    def delete(self, cg_id: str) -> None:
+    def delete(self, cg_id: UUID) -> None:
         """
         Deletes existing config-group with given ID
         """
-        self.endpoint.delete_config_group(cg_id)
+        self._endpoints.delete_config_group(cg_id)
 
     def deploy(self, cg_id: str, device_ids: list) -> ConfigGroupDeployResponse:
         """
@@ -83,7 +86,7 @@ class ConfigGroupAPI:
             devices.append(DeviceId(id=device_id))
 
         payload = ConfigGroupDeployPayload(devices=devices)
-        return self.endpoint.deploy(config_group_id=cg_id, payload=payload)
+        return self._endpoints.deploy(config_group_id=cg_id, payload=payload)
 
     def disassociate(self, cg_id: str, device_ids: list) -> ConfigGroupDisassociateResponse:
         """
@@ -94,7 +97,7 @@ class ConfigGroupAPI:
             devices.append(DeviceId(id=device_id))
 
         payload = ConfigGroupAssociatePayload(devices=devices)
-        return self.endpoint.disassociate(config_group_id=cg_id, payload=payload)
+        return self._endpoints.disassociate(config_group_id=cg_id, payload=payload)
 
     def edit(
         self, cg_id: str, name: str, description: str, solution: Solution, profile_ids: list
@@ -108,13 +111,24 @@ class ConfigGroupAPI:
             profiles.append(ProfileId(id=profile_id))
         payload = ConfigGroupEditPayload(name=name, description=description, solution=solution, profiles=profiles)
 
-        return self.endpoint.edit_config_group(config_group_id=cg_id, payload=payload)
+        return self._endpoints.edit_config_group(config_group_id=cg_id, payload=payload)
+
+    @overload
+    def get(self) -> DataSequence[ConfigGroup]:
+        ...
 
-    def get(self) -> ConfigGroupResponsePayload:
+    @overload
+    def get(self, group_id: UUID) -> ConfigGroup:
+        ...
+
+    def get(self, group_id: Optional[UUID] = None) -> Any:
         """
-        Gets list of existing config-groups
+        Gets list of existing config-groups or single config-group with given ID
+        If given ID is not correct return None
         """
-        return self.endpoint.get()
+        if group_id is None:
+            return self._endpoints.get()
+        return self._endpoints.get().filter(id=group_id).single_or_default()
 
     def update_variables(self, cg_id: str, solution: Solution, device_variables: list) -> None:
         """
@@ -122,4 +136,15 @@ class ConfigGroupAPI:
         """
         payload = ConfigGroupVariablesEditPayload(solution=solution, devices=device_variables)
 
-        self.endpoint.update_variables(config_group_id=cg_id, payload=payload)
+        self._endpoints.update_variables(config_group_id=cg_id, payload=payload)
+
+    def delete_all(self) -> None:
+        """
+        Deletes all config-group
+        """
+        config_groups = self.get()
+        for config_group in config_groups:
+            if config_group.devices:
+                self.disassociate(str(config_group.id), config_group.devices)
+
+            self.delete(config_group.id)

catalystwan/api/configuration_groups/parcel.py

@@ -1,15 +1,35 @@
-# Copyright 2023 Cisco Systems, Inc. and its affiliates
+# Copyright 2024 Cisco Systems, Inc. and its affiliates
+
+from typing import Any, Dict, Generic, List, Literal, Optional, Sequence, Tuple, TypeVar
+
+from pydantic import (
+    AliasPath,
+    BaseModel,
+    ConfigDict,
+    Field,
+    PrivateAttr,
+    SerializationInfo,
+    SerializerFunctionWrapHandler,
+    model_serializer,
+)
+from pydantic.alias_generators import to_camel
+from typing_extensions import get_origin
+
+from catalystwan.exceptions import CatalystwanException
+from catalystwan.models.common import VersionedField
 
-from enum import Enum
-from typing import Any, Dict, Generic, Literal, Optional, TypeVar, get_origin
+T = TypeVar("T")
 
-from pydantic import AliasPath, BaseModel, ConfigDict, Field, PrivateAttr, model_serializer
 
-T = TypeVar("T")
+class _ParcelEntry(BaseModel):
+    def __hash__(self) -> int:
+        return hash(self.model_dump_json())
 
 
 class _ParcelBase(BaseModel):
-    model_config = ConfigDict(extra="forbid", arbitrary_types_allowed=True, populate_by_name=True)
+    model_config = ConfigDict(
+        extra="allow", arbitrary_types_allowed=True, populate_by_name=True, json_schema_mode_override="validation"
+    )
     parcel_name: str = Field(
         min_length=1,
         max_length=128,
@@ -24,45 +44,64 @@ class _ParcelBase(BaseModel):
         description="Set the parcel description",
     )
     data: Optional[Any] = None
+    entries: Optional[Sequence[_ParcelEntry]] = Field(default=None, validation_alias=AliasPath("data", "entries"))
     _parcel_data_key: str = PrivateAttr(default="data")
 
     @model_serializer(mode="wrap")
-    def envelope_parcel_data(self, handler) -> Dict[str, Any]:
+    def envelope_parcel_data(self, handler: SerializerFunctionWrapHandler, info: SerializationInfo) -> Dict[str, Any]:
+        """
+        serializes model fields with respect to field validation_alias,
+        sub-classing parcel fields can be defined like following:
+        >>> entries: List[SecurityZoneListEntry] = Field(default=[], validation_alias=AliasPath("data", "entries"))
+
+        "data" is default _parcel_data_key which must match validation_alias prefix,
+        this attribute can be overriden in sub-class when needed
+        """
         model_dict = handler(self)
         model_dict[self._parcel_data_key] = {}
         remove_keys = []
+        replaced_keys: Dict[str, Tuple[str, str]] = {}
 
+        # enveloping
         for key in model_dict.keys():
             field_info = self.model_fields.get(key)
             if field_info and isinstance(field_info.validation_alias, AliasPath):
                 aliases = field_info.validation_alias.convert_to_aliases()
                 if aliases and aliases[0] == self._parcel_data_key and len(aliases) == 2:
                     model_dict[self._parcel_data_key][aliases[1]] = model_dict[key]
+                    replaced_keys[key] = (self._parcel_data_key, str(aliases[1]))
                     remove_keys.append(key)
         for key in remove_keys:
             del model_dict[key]
-        return model_dict
 
+        # versioned field update
+        model_dict = VersionedField.dump(self.model_fields, model_dict, info, replaced_keys)
 
-class OptionType(str, Enum):
-    GLOBAL = "global"
-    DEFAULT = "default"
-    VARIABLE = "variable"
+        return model_dict
 
+    @classmethod
+    def _get_parcel_type(cls) -> str:
+        field_info = cls.model_fields.get("type_")
+        if field_info is not None:
+            return str(field_info.default)
+        raise CatalystwanException(f"{cls.__name__} field parcel type is not set.")
 
-class ParcelAttribute(BaseModel):
-    model_config = ConfigDict(extra="forbid")
-    option_type: OptionType = Field(serialization_alias="optionType", validation_alias="optionType")
+    def remove_duplicated_entries(self) -> None:
+        if self.entries:
+            self.entries = list(set(self.entries))
 
 
 # https://github.com/pydantic/pydantic/discussions/6090
 # Usage: Global[str](value="test")
-class Global(ParcelAttribute, Generic[T]):
-    option_type: OptionType = Field(
-        default=OptionType.GLOBAL, serialization_alias="optionType", validation_alias="optionType"
-    )
+class Global(BaseModel, Generic[T]):
+    model_config = ConfigDict(populate_by_name=True, alias_generator=to_camel)
+    option_type: Literal["global"] = "global"
     value: T
 
+    def __bool__(self) -> bool:
+        # if statements use __len__ when __bool__ is not defined
+        return True
+
     def __len__(self) -> int:
         if isinstance(self.value, (str, list)):
             return len(self.value)
@@ -78,19 +117,27 @@ class Global(ParcelAttribute, Generic[T]):
             return self.value <= other
         return False
 
+    def __hash__(self) -> int:
+        return hash(self.value)
 
-class Variable(ParcelAttribute):
-    option_type: OptionType = Field(
-        default=OptionType.VARIABLE, serialization_alias="optionType", validation_alias="optionType"
-    )
+
+class Variable(BaseModel):
+    model_config = ConfigDict(populate_by_name=True, alias_generator=to_camel)
+    option_type: Literal["variable"] = "variable"
     value: str = Field(pattern=r"^\{\{[.\/\[\]a-zA-Z0-9_-]+\}\}$", min_length=1, max_length=64)
 
 
-class Default(ParcelAttribute, Generic[T]):
-    option_type: OptionType = Field(
-        default=OptionType.DEFAULT, serialization_alias="optionType", validation_alias="optionType"
-    )
-    value: Any
+class Default(BaseModel, Generic[T]):
+    model_config = ConfigDict(populate_by_name=True, alias_generator=to_camel)
+    option_type: Literal["default"] = "default"
+    value: Optional[T] = None
+
+
+def as_optional_global(value: Any, generic_alias: Any = None):
+    if value is None:
+        return None
+
+    return as_global(value, generic_alias)
 
 
 def as_global(value: Any, generic_alias: Any = None):
@@ -104,10 +151,16 @@ def as_global(value: Any, generic_alias: Any = None):
         Global[Any]: global option type object
     """
     if generic_alias is None:
+        if isinstance(value, list):
+            if len(value) == 0:
+                return Global[List](value=list())  # type: ignore
+            return Global[List[type(value[0])]](value=value)  # type: ignore
         return Global[type(value)](value=value)  # type: ignore
     elif get_origin(generic_alias) is Literal:
         return Global[generic_alias](value=value)  # type: ignore
-    TypeError("Inappropriate type for argument generic_alias")
+    raise TypeError(
+        f"Inappropriate type origin: {generic_alias} {get_origin(generic_alias)} for argument generic_alias"
+    )
 
 
 def as_variable(value: str):
@@ -119,6 +172,8 @@ def as_variable(value: str):
     Returns:
         Variable: variable option type object
     """
+    if not value.startswith("{{") and not value.endswith("}}"):
+        value = "{{" + value + "}}"
     return Variable(value=value)
 
 
@@ -132,8 +187,23 @@ def as_default(value: Any, generic_alias: Any = None):
     Returns:
         Default[Any]: default option type object
     """
+    if value is None:
+        return Default[None](value=None)
     if generic_alias is None:
+        if isinstance(value, list):
+            if len(value) == 0:
+                return Default[List](value=list())  # type: ignore
+            return Default[List[type(value[0])]](value=value)  # type: ignore
         return Default[type(value)](value=value)  # type: ignore
     elif get_origin(generic_alias) is Literal:
         return Default[generic_alias](value=value)  # type: ignore
-    TypeError("Inappropriate type for argument generic_alias")
+    raise TypeError(
+        f"Inappropriate type origin: {generic_alias} {get_origin(generic_alias)} for argument generic_alias"
+    )
+
+
+def as_optional_global_or_variable(value: Any, generic_alias: Any = None):
+    if isinstance(value, str) and value.startswith("{{") and value.endswith("}}"):
+        return as_variable(value)
+    else:
+        return as_optional_global(value, generic_alias)