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

catalystwan/__init__.py

@@ -13,7 +13,8 @@ from typing import Callable, Final, List, Optional
 
 import urllib3
 
-USER_AGENT = f"{__package__}/{metadata.version(__package__)}"
+PACKAGE_VERSION = metadata.version(__package__)
+USER_AGENT = f"{__package__}/{PACKAGE_VERSION}"
 
 
 def with_proc_info_header(method: Callable[..., str]) -> Callable[..., str]:
@@ -75,7 +76,7 @@ __version__ = metadata.version(__package__)
 pkg_src_list = list_package_sources()
 
 
-if environ.get("catalystwan_devel") is not None:
+if environ.get("catalystwan_devel") is not None or environ.get("CATALYSTWAN_DEVEL") is not None:
     urllib3.disable_warnings(urllib3.exceptions.InsecureRequestWarning)
     catalystwan_logger = logging.getLogger(__name__)
     logging.config.fileConfig(LOGGING_CONF_DIR, disable_existing_loggers=False)

catalystwan/api/administration.py

@@ -1,4 +1,4 @@
-# Copyright 2022 Cisco Systems, Inc. and its affiliates
+# Copyright 2024 Cisco Systems, Inc. and its affiliates
 
 from __future__ import annotations
 
@@ -34,6 +34,7 @@ from catalystwan.endpoints.administration_user_and_group import (
     UserUpdateRequest,
 )
 from catalystwan.exceptions import CatalystwanDeprecationWarning, CatalystwanException
+from catalystwan.models.settings import ThreatGridApi
 from catalystwan.typed_list import DataSequence
 from catalystwan.utils.creation_tools import asdict, create_dataclass
 
@@ -384,7 +385,14 @@ class AdministrationSettingsAPI:
     def update(self, payload: Organization) -> bool:
         ...
 
-    def update(self, payload: Union[Organization, Certificate, Password, Vbond]) -> bool:
+    @overload
+    def update(self, payload: ThreatGridApi) -> bool:
+        ...
+
+    def update(self, payload: Union[Organization, Certificate, Password, Vbond, ThreatGridApi]) -> bool:
+        if isinstance(payload, ThreatGridApi):
+            created_threat = self.__update_thread_grid_api(payload)
+            return created_threat is not None
         json_payload = asdict(payload)  # type: ignore
         if isinstance(payload, Organization):
             response = self.__update_organization(json_payload)
@@ -414,6 +422,9 @@ class AdministrationSettingsAPI:
         endpoint = "/dataservice/settings/configuration/device"
         return self.session.post(endpoint, json=payload)
 
+    def __update_thread_grid_api(self, payload: ThreatGridApi) -> DataSequence[ThreatGridApi]:
+        return self.session.endpoints.configuration_settings.edit_threat_grid_api_key(payload)
+
     @deprecated(
         "Use .endpoints.configuration_settings.edit_organizations() instead", category=CatalystwanDeprecationWarning
     )

catalystwan/api/api_container.py

@@ -15,10 +15,11 @@ from catalystwan.api.administration import (
 )
 from catalystwan.api.alarms_api import AlarmsAPI
 from catalystwan.api.basic_api import DevicesAPI, DeviceStateAPI
+from catalystwan.api.builders import BuilderAPI
 from catalystwan.api.config_device_inventory_api import ConfigurationDeviceInventoryAPI
 from catalystwan.api.config_group_api import ConfigGroupAPI
 from catalystwan.api.dashboard_api import DashboardAPI
-from catalystwan.api.feature_profile_api import SDRoutingFeatureProfilesAPI
+from catalystwan.api.feature_profile_api import SDRoutingFeatureProfilesAPI, SDWANFeatureProfilesAPI
 from catalystwan.api.logs_api import LogsAPI
 from catalystwan.api.omp_api import OmpAPI
 from catalystwan.api.packet_capture_api import PacketCaptureAPI
@@ -68,3 +69,5 @@ class APIContainer:
         self.sessions = SessionsAPI(session)
         self.policy = PolicyAPI(session)
         self.sd_routing_feature_profiles = SDRoutingFeatureProfilesAPI(session)
+        self.sdwan_feature_profiles = SDWANFeatureProfilesAPI(session)
+        self.builders = BuilderAPI(session)

catalystwan/api/builders/__init__.py

@@ -0,0 +1,14 @@
+# Copyright 2024 Cisco Systems, Inc. and its affiliates
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from catalystwan.api.builders.feature_profiles.builder_factory import FeatureProfileBuilderFactory
+
+if TYPE_CHECKING:
+    from catalystwan.session import ManagerSession
+
+
+class BuilderAPI:
+    def __init__(self, session: ManagerSession):
+        self.feature_profiles = FeatureProfileBuilderFactory(session=session)

catalystwan/api/builders/feature_profiles/application_priority.py

@@ -0,0 +1,58 @@
+# Copyright 2024 Cisco Systems, Inc. and its affiliates
+from __future__ import annotations
+
+import logging
+from typing import TYPE_CHECKING, List
+from uuid import UUID
+
+from catalystwan.api.builders.feature_profiles.report import FeatureProfileBuildReport, handle_create_parcel
+from catalystwan.api.feature_profile_api import ApplicationPriorityFeatureProfileAPI
+from catalystwan.models.configuration.feature_profile.common import FeatureProfileCreationPayload
+from catalystwan.models.configuration.feature_profile.sdwan.application_priority import AnyApplicationPriorityParcel
+
+logger = logging.getLogger(__name__)
+
+if TYPE_CHECKING:
+    from catalystwan.session import ManagerSession
+
+
+class ApplicationPriorityFeatureProfileBuilder:
+    """
+    A class for building Application Priority feature profiles.
+    """
+
+    def __init__(self, session: ManagerSession) -> None:
+        """
+        Args:
+            session (ManagerSession): The ManagerSession object used for API communication.
+            profile_uuid (UUID): The UUID of the profile.
+        """
+        self._profile: FeatureProfileCreationPayload
+        self._api = ApplicationPriorityFeatureProfileAPI(session)
+        self._parcels: List[AnyApplicationPriorityParcel] = []
+
+    def add_profile_name_and_description(self, feature_profile: FeatureProfileCreationPayload) -> None:
+        """
+        Adds a name and description to the feature profile.
+
+        Args:
+            feature_profile (FeatureProfileCreationPayload): Payload containing the name and description.
+
+        Returns:
+            None
+        """
+        self._profile = feature_profile
+
+    def add_parcel(self, parcel: AnyApplicationPriorityParcel) -> None:
+        self._parcels.append(parcel)
+
+    def build(self) -> FeatureProfileBuildReport:
+        profile_uuid = self._api.create_profile(self._profile.name, self._profile.description).id
+        self.build_report = FeatureProfileBuildReport(profile_uuid=profile_uuid, profile_name=self._profile.name)
+        for parcel in self._parcels:
+            self._create_parcel(profile_uuid, parcel)
+        return self.build_report
+
+    @handle_create_parcel
+    def _create_parcel(self, profile_uuid: UUID, parcel: AnyApplicationPriorityParcel) -> UUID:
+        return self._api.create_parcel(profile_uuid, parcel).id

catalystwan/api/builders/feature_profiles/builder_factory.py

@@ -0,0 +1,59 @@
+# Copyright 2024 Cisco Systems, Inc. and its affiliates
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Callable, Mapping, Union
+
+from catalystwan.api.builders.feature_profiles.application_priority import ApplicationPriorityFeatureProfileBuilder
+from catalystwan.api.builders.feature_profiles.cli import CliFeatureProfileBuilder
+from catalystwan.api.builders.feature_profiles.other import OtherFeatureProfileBuilder
+from catalystwan.api.builders.feature_profiles.service import ServiceFeatureProfileBuilder
+from catalystwan.api.builders.feature_profiles.system import SystemFeatureProfileBuilder
+from catalystwan.api.builders.feature_profiles.transport import TransportAndManagementProfileBuilder
+from catalystwan.api.builders.feature_profiles.uc_voice import UcVoiceFeatureProfileBuilder
+from catalystwan.exceptions import CatalystwanException
+from catalystwan.models.configuration.feature_profile.common import ProfileType
+
+if TYPE_CHECKING:
+    from catalystwan.session import ManagerSession
+
+FeatureProfileBuilder = Union[
+    ServiceFeatureProfileBuilder,
+    SystemFeatureProfileBuilder,
+    OtherFeatureProfileBuilder,
+    TransportAndManagementProfileBuilder,
+    CliFeatureProfileBuilder,
+    ApplicationPriorityFeatureProfileBuilder,
+    UcVoiceFeatureProfileBuilder
+]
+
+BUILDER_MAPPING: Mapping[ProfileType, Callable] = {
+    "service": ServiceFeatureProfileBuilder,
+    "system": SystemFeatureProfileBuilder,
+    "other": OtherFeatureProfileBuilder,
+    "transport": TransportAndManagementProfileBuilder,
+    "cli": CliFeatureProfileBuilder,
+    "application-priority": ApplicationPriorityFeatureProfileBuilder,
+    "uc-voice": UcVoiceFeatureProfileBuilder,
+}
+
+
+class FeatureProfileBuilderFactory:
+    def __init__(self, session: ManagerSession):
+        self.session = session
+
+    def create_builder(self, profile_type: ProfileType) -> FeatureProfileBuilder:
+        """
+        Creates a builder for the specified feature profile.
+
+        Args:
+            feature_profile_name (str): The name of the feature profile.
+
+        Returns:
+            FeatureProfileBuilder: The builder for the specified feature profile.
+
+        Raises:
+            CatalystwanException: If the feature profile is not found or has an unsupported type.
+        """
+        if profile_type not in BUILDER_MAPPING:
+            raise CatalystwanException(f"Unsupported builder for type {profile_type}")
+        return BUILDER_MAPPING[profile_type](self.session)

catalystwan/api/builders/feature_profiles/cli.py

@@ -0,0 +1,76 @@
+# Copyright 2024 Cisco Systems, Inc. and its affiliates
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, List
+from uuid import UUID
+
+from catalystwan.api.builders.feature_profiles.report import FeatureProfileBuildReport, handle_create_parcel
+from catalystwan.api.feature_profile_api import CliFeatureProfileAPI
+from catalystwan.endpoints.configuration.feature_profile.sdwan.cli import CliFeatureProfile
+from catalystwan.models.configuration.feature_profile.common import FeatureProfileCreationPayload
+from catalystwan.models.configuration.feature_profile.sdwan.cli import AnyCliParcel
+
+if TYPE_CHECKING:
+    from catalystwan.session import ManagerSession
+
+
+class CliFeatureProfileBuilder:
+    """
+    A class for building Cli feature profiles.
+    """
+
+    def __init__(self, session: ManagerSession) -> None:
+        """
+        Initialize a new instance of the Cli class.
+
+        Args:
+            session (ManagerSession): The ManagerSession object used for API communication.
+            profile_uuid (UUID): The UUID of the profile.
+        """
+        self._profile: FeatureProfileCreationPayload
+        self._api = CliFeatureProfileAPI(session)
+        self._endpoints = CliFeatureProfile(session)
+        self._cli_configs: List[AnyCliParcel] = list()
+
+    def add_profile_name_and_description(self, feature_profile: FeatureProfileCreationPayload) -> None:
+        """
+        Adds a name and description to the feature profile.
+
+        Args:
+            name (str): The name of the feature profile.
+            description (str): The description of the feature profile.
+
+        Returns:
+            None
+        """
+        self._profile = feature_profile
+
+    def add_parcel(self, parcel: AnyCliParcel) -> None:
+        """
+        Adds a parcel to the feature profile.
+
+        Args:
+            parcel (AnyCliParcel): The parcel to add.
+
+        Returns:
+            None
+        """
+        self._cli_configs.append(parcel)
+
+    def build(self) -> FeatureProfileBuildReport:
+        """
+        Builds the feature profile.
+
+        Returns:
+            UUID: The UUID of the created feature profile.
+        """
+
+        profile_uuid = self._endpoints.create_profile(self._profile).id
+        self.build_report = FeatureProfileBuildReport(profile_uuid=profile_uuid, profile_name=self._profile.name)
+        for config_parcel in self._cli_configs:
+            self._create_parcel(profile_uuid, config_parcel)
+        return self.build_report
+
+    @handle_create_parcel
+    def _create_parcel(self, profile_uuid: UUID, parcel: AnyCliParcel) -> UUID:
+        return self._api.create_parcel(profile_uuid, parcel).id

catalystwan/api/builders/feature_profiles/mixins.py

@@ -0,0 +1,44 @@
+# Copyright 2023 Cisco Systems, Inc. and its affiliates
+from __future__ import annotations
+
+from typing import Dict, List, Set, Tuple
+from uuid import UUID
+
+from catalystwan.models.configuration.feature_profile.sdwan.trackers import Tracker, TrackerGroup
+
+
+class TrackerMixin:
+    def init_tracker(self) -> None:
+        self._shared_trackers: Dict[str, UUID] = {}
+        self._trackers: List[Tuple[Set[UUID], Tracker]] = []
+        self._tracker_groups: List[Tuple[Set[UUID], TrackerGroup, List[Tracker]]] = []
+        self._interface_tag_to_existing_tracker: Dict[UUID, Tuple[UUID, str]] = {}
+
+    def _create_parcel(self, profile_uuid: UUID, tracker: Tracker | TrackerGroup) -> UUID:
+        raise NotImplementedError()
+
+    def create_trackers(self, profile_uuid: UUID) -> None:
+        for tracker_group_tags, tracker_group, trackers in self._tracker_groups:
+            trackers_uuids: List[UUID] = []
+            for tracker_ in trackers:
+                tracker_uuid = self._create_parcel(profile_uuid, tracker_)
+                if tracker_uuid:
+                    trackers_uuids.append(tracker_uuid)
+                    self._shared_trackers[tracker_.parcel_name] = tracker_uuid
+
+            for tracker_uuid in trackers_uuids:
+                tracker_group.add_ref(tracker_uuid)
+
+            tracker_group_uuid = self._create_parcel(profile_uuid, tracker_group)
+            if tracker_group_uuid:
+                for tag in tracker_group_tags:
+                    self._interface_tag_to_existing_tracker[tag] = tracker_group_uuid, tracker_group._get_parcel_type()
+
+        for tracker_tags, tracker in self._trackers:
+            if tracker.parcel_name in self._shared_trackers:
+                created_tracker_uuid = self._shared_trackers[tracker.parcel_name]
+            else:
+                created_tracker_uuid = self._create_parcel(profile_uuid, tracker)
+            if created_tracker_uuid:
+                for tag in tracker_tags:
+                    self._interface_tag_to_existing_tracker[tag] = (created_tracker_uuid, tracker._get_parcel_type())

catalystwan/api/builders/feature_profiles/other.py

@@ -0,0 +1,79 @@
+# Copyright 2024 Cisco Systems, Inc. and its affiliates
+from __future__ import annotations
+
+import logging
+from typing import TYPE_CHECKING, List
+from uuid import UUID
+
+from catalystwan.api.builders.feature_profiles.report import FeatureProfileBuildReport, handle_create_parcel
+from catalystwan.api.feature_profile_api import OtherFeatureProfileAPI
+from catalystwan.endpoints.configuration.feature_profile.sdwan.other import OtherFeatureProfile
+from catalystwan.models.configuration.feature_profile.common import FeatureProfileCreationPayload
+from catalystwan.models.configuration.feature_profile.sdwan.other import AnyOtherParcel
+
+logger = logging.getLogger(__name__)
+
+if TYPE_CHECKING:
+    from catalystwan.session import ManagerSession
+
+
+class OtherFeatureProfileBuilder:
+    """
+    A class for building Other feature profiles.
+    """
+
+    def __init__(self, session: ManagerSession) -> None:
+        """
+        Initialize a new instance of the Service class.
+
+        Args:
+            session (ManagerSession): The ManagerSession object used for API communication.
+            profile_uuid (UUID): The UUID of the profile.
+        """
+        self._profile: FeatureProfileCreationPayload
+        self._api = OtherFeatureProfileAPI(session)
+        self._endpoints = OtherFeatureProfile(session)
+        self._independent_items: List[AnyOtherParcel] = []
+
+    def add_profile_name_and_description(self, feature_profile: FeatureProfileCreationPayload) -> None:
+        """
+        Adds a name and description to the feature profile.
+
+        Args:
+            name (str): The name of the feature profile.
+            description (str): The description of the feature profile.
+
+        Returns:
+            None
+        """
+        self._profile = feature_profile
+
+    def add_parcel(self, parcel: AnyOtherParcel) -> None:
+        """
+        Adds a parcel to the feature profile.
+
+        Args:
+            parcel (AnySystemParcel): The parcel to add.
+
+        Returns:
+            None
+        """
+        self._independent_items.append(parcel)
+
+    def build(self) -> FeatureProfileBuildReport:
+        """
+        Builds the feature profile.
+
+        Returns:
+            UUID: The UUID of the created feature profile.
+        """
+
+        profile_uuid = self._endpoints.create_sdwan_other_feature_profile(self._profile).id
+        self.build_report = FeatureProfileBuildReport(profile_uuid=profile_uuid, profile_name=self._profile.name)
+        for parcel in self._independent_items:
+            self._create_parcel(profile_uuid, parcel)
+        return self.build_report
+
+    @handle_create_parcel
+    def _create_parcel(self, profile_uuid: UUID, parcel: AnyOtherParcel) -> UUID:
+        return self._api.create_parcel(profile_uuid, parcel).id

catalystwan/api/builders/feature_profiles/report.py

@@ -0,0 +1,155 @@
+# Copyright 2023 Cisco Systems, Inc. and its affiliates
+import functools
+import logging
+from typing import Any, List, Optional, Tuple, Union
+from uuid import UUID
+
+from pydantic import BaseModel, ConfigDict, Field
+from requests import PreparedRequest, Request, Response
+
+from catalystwan.exceptions import ManagerErrorInfo, ManagerHTTPError
+from catalystwan.models.configuration.feature_profile.parcel import AnyParcel
+
+logger = logging.getLogger(__name__)
+
+
+def handle_create_parcel(func):
+    @functools.wraps(func)
+    def wrapper(self, profile_uuid: UUID, parcel: AnyParcel, *args, **kwargs) -> Optional[UUID]:
+        try:
+            uuid = func(self, profile_uuid, parcel, *args, **kwargs)
+            self.build_report.add_created_parcel(parcel.parcel_name, uuid)
+            return uuid
+        except ManagerHTTPError as e:
+            self.build_report.add_failed_parcel(
+                parcel_name=parcel.parcel_name,
+                parcel_type=parcel._get_parcel_type(),
+                error=e,
+            )
+            return None
+
+    return wrapper
+
+
+class FailedRequestDetails(BaseModel):
+    method: str
+    url: str
+    body: str
+
+    @classmethod
+    def from_request(cls, request: Union[Request, PreparedRequest, Any]) -> "FailedRequestDetails":
+        if isinstance(request, (Request, PreparedRequest)):
+            return cls(
+                method=str(request.method),
+                url=str(request.url),
+                body=str(request.body if hasattr(request, "body") else ""),
+            )
+        return cls.as_empty()
+
+    @classmethod
+    def as_empty(cls) -> "FailedRequestDetails":
+        return cls(method="", url="", body="")
+
+
+class ResponseDetails(BaseModel):
+    status_code: int
+    reason: str
+
+    @classmethod
+    def from_response(cls, response: Union[Response, Any]) -> "ResponseDetails":
+        if isinstance(response, Response):
+            return cls(status_code=response.status_code, reason=response.reason)
+        return cls.as_empty()
+
+    @classmethod
+    def as_empty(cls) -> "ResponseDetails":
+        return cls(status_code=-1, reason="")
+
+
+class FailedParcel(BaseModel):
+    model_config = ConfigDict(populate_by_name=True)
+    parcel_name: str = Field(serialization_alias="parcelName", validation_alias="parcelName")
+    parcel_type: str = Field(serialization_alias="parcelType", validation_alias="parcelType")
+    error_info: Union[ManagerErrorInfo, str] = Field(serialization_alias="errorInfo", validation_alias="errorInfo")
+    request_details: Optional[FailedRequestDetails] = Field(
+        default=None, serialization_alias="requestDetails", validation_alias="requestDetails"
+    )
+    response_details: Optional[ResponseDetails] = Field(
+        default=None, serialization_alias="responseDetails", validation_alias="responseDetails"
+    )
+
+    @classmethod
+    def from_error(
+        cls,
+        parcel_name: str,
+        parcel_type: str,
+        error: ManagerHTTPError,
+    ):
+        return cls(
+            parcel_name=parcel_name,
+            parcel_type=parcel_type,
+            error_info=error.info,
+            request_details=FailedRequestDetails.from_request(error.request),
+            response_details=ResponseDetails.from_response(error.response),
+        )
+
+
+class FeatureProfileBuildReport(BaseModel):
+    model_config = ConfigDict(populate_by_name=True)
+    profile_name: str = Field(serialization_alias="profileName", validation_alias="profileName")
+    profile_uuid: UUID = Field(serialization_alias="profileUuid", validation_alias="profileUuid")
+    created_parcels: List[Tuple[str, UUID]] = Field(
+        default_factory=list, serialization_alias="createdParcels", validation_alias="createdParcels"
+    )
+    failed_parcels: List[FailedParcel] = Field(
+        default_factory=list, serialization_alias="failedParcels", validation_alias="failedParcels"
+    )
+
+    def add_created_parcel(self, parcel_name: str, parcel_uuid: UUID) -> None:
+        self.created_parcels.append((parcel_name, parcel_uuid))
+
+    def add_failed_parcel(
+        self,
+        parcel_name: str,
+        parcel_type: str,
+        error: ManagerHTTPError,
+    ) -> None:
+        self.failed_parcels.append(
+            FailedParcel.from_error(
+                parcel_name=parcel_name,
+                parcel_type=parcel_type,
+                error=error,
+            )
+        )
+
+
+def hande_failed_sub_parcel(build_report: FeatureProfileBuildReport, parent: AnyParcel, subparcel: AnyParcel) -> None:
+    parent_failed_to_create_message = (
+        f"Parent parcel: {parent.parcel_name} failed to create. This subparcel is dependent on it."
+    )
+    build_report.failed_parcels.append(
+        FailedParcel(
+            parcel_name=subparcel.parcel_name,
+            parcel_type=subparcel._get_parcel_type(),
+            error_info=parent_failed_to_create_message,
+        ),
+    )
+
+
+class handle_association_request:
+    def __init__(self, build_report: FeatureProfileBuildReport, parcel: AnyParcel) -> None:
+        self.build_report = build_report
+        self.parcel = parcel
+
+    def __enter__(self) -> "handle_association_request":
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        if exc_type is not None:
+            if issubclass(exc_type, ManagerHTTPError):
+                self.build_report.add_failed_parcel(
+                    parcel_name=self.parcel.parcel_name, parcel_type=self.parcel._get_parcel_type(), error=exc_val
+                )
+            else:
+                logger.exception(exc_val)
+        return True