catalystwan 0.40.2.dev1__py3-none-any.whl → 2.0.0a1__py3-none-any.whl

catalystwan/api/templates/README.md

@@ -1,101 +0,0 @@
-# How to use
-
-## Feature Template Creation
-
-```python
-from catalystwan.api.templates.models.omp_vsmart_model import OMPvSmart
-
-omp_vsmart = OMPvSmart(
-    name="my_first_template",
-    description="NA",
-    device_models=["vsmart"]
-    
-)
-
-session.api.templates.create(omp_vsmart)
-```
-
-## Add new Feature Template in Cisco Catalyst WAN SDK
-
-These steps will help you to automate feature template creation. We'll explain what to do and why, so everyone will have deep understanding how our templates work. In the example we will try to create `OMP` Feature Template for vSmart.
-
-1. Get your template type name and version.
-    >Note: display name is not template type name!
-
-- For example, you could extract it from response body. Go to your Manager and create any template which you would like to automate in catalystwan. Send template creation request and check for `templateType` and `templateMinVersion` variable names. `OMP` (display name) for vSmart has `omp-vsmart` template type name.
-
-2. With corresponding `templateType` we are able to create new class which implements `FeatureTemplate` interface. Create new file in `catalystwan\api\templates\models\` and copy-paste the code and change name of the class with its type attribute.
-
-```python
-from pathlib import Path
-from typing import ClassVar
-from pydantic import ConfigDict
-from catalystwan.api.templates.feature_template import FeatureTemplate
-
-
-class OMPvSmart(FeatureTemplate):
-    model_config = ConfigDict(arbitrary_types_allowed=True, populate_by_name=True)
-
-    payload_path: ClassVar[Path] = Path(__file__).parent / "DEPRECATED"
-    type: ClassVar[str] = "omp-vsmart"
-```
-
-3. (This step is temporary) Find `is_created_by_generator` method in `template_api` and add your new template class.
-
-```python
-ported_templates = (..., OMPvSmart)
-```
-
-NOTE: This step will be removed once all template payloads will be generated automatically.
-
-4. (This step is temporary) Find `available_models` definition in 'supported' and add your new template class.
-
-```python
-available_models = {
-    (...)
-    'omp_vsmart': OMPvSmart
-}
-```
-
-NOTE: This step will be removed once all template payloads will be generated dynamically.
-
-5. We can try to create our first template with default values.
-
-```python
-omp_vsmart = OMPvSmart(
-    name="my_first_template",
-    description="NA",
-    device_models=["vsmart"]
-)
-
-session.api.templates.create(omp_vsmart)
-```
-
-If everything went successfuly, we will get similar message:
-
-`Template my_first_template (FeatureTemplate) was created successfully (7e56acdd-640e-45dc-9335-87abc697995f).`
-
-6. We can check whether our template is created sucessfully in Manager manually. If there is an error, please create an issue with error and try go to the 7th step.
-
-### Customize Feature Template fields
-
-7. Run below code with already created session and changed corresponding variables.
-
-```python
-# TODO: Use 2nd layer.
-import json
-
-
-template_type = "omp-vsmart" # Change this value
-template_version = "15.0.0" # Change this value
-endpoint = f"/dataservice/template/feature/types/definition/{template_type}/{template_version}"
-
-schema = session.get(url=endpoint).json()
-
-with open(f"response_{template_type}.json", "w") as f:
-    f.write(json.dumps(schema, indent=4))
-```
-
-8. Open `response_{template_type}.json` file.
-
-9. Find `fields` key. The value should be list of dictionaries. Get every possible key in the dictionary and fill our class with every possible key. You can find the code in `catalystwan\api\templates\models\omp_vsmart_model.py` file.

catalystwan/api/templates/bool_str.py

@@ -1,6 +0,0 @@
-# Copyright 2024 Cisco Systems, Inc. and its affiliates
-
-from pydantic import PlainSerializer
-from typing_extensions import Annotated
-
-BoolStr = Annotated[bool, PlainSerializer(lambda x: str(x).lower(), return_type=str, when_used="json-unless-none")]

catalystwan/api/templates/cli_template.py

@@ -1,236 +0,0 @@
-# Copyright 2023 Cisco Systems, Inc. and its affiliates
-
-from __future__ import annotations
-
-import json
-import logging
-from difflib import Differ
-from typing import TYPE_CHECKING, List
-
-from attr import define  # type: ignore
-from ciscoconfparse import CiscoConfParse  # type: ignore
-from requests.exceptions import HTTPError
-
-from catalystwan.dataclasses import Device
-from catalystwan.exceptions import TemplateTypeError
-from catalystwan.models.common import DeviceModel
-from catalystwan.utils.template_type import TemplateType
-
-logger = logging.getLogger(__name__)
-
-if TYPE_CHECKING:
-    from catalystwan.session import ManagerSession
-
-
-@define
-class CLITemplate:
-    template_name: str
-    template_description: str
-    device_model: DeviceModel
-    config: CiscoConfParse = CiscoConfParse([], factory=True)
-
-    def load(self, session: ManagerSession, id: str) -> CiscoConfParse:
-        """Load CLI config from template.
-        Args:
-            id (str): The template id from which load config.
-        Raises:
-            TemplateTypeError: wrong template type - CLI required.
-        Returns:
-            CiscoConfParse: Loaded template.
-        """
-        endpoint = f"/dataservice/template/device/object/{id}"
-        config = session.get_json(endpoint)
-        if TemplateType(config["configType"]) == TemplateType.FEATURE:
-            raise TemplateTypeError(config["templateName"])
-        self.config = CiscoConfParse(config["templateConfiguration"].splitlines())
-        return self.config
-
-    def load_running(self, session: ManagerSession, device: Device) -> CiscoConfParse:
-        """Load running config from device.
-
-        Args:
-            session: logged in API client session
-            device: The device from which load config.
-
-        Returns:
-            CiscoConfParse: A working configuration on the machine.
-        """
-        encoded_uuid = device.uuid.replace("/", "%2F")
-        endpoint = f"/dataservice/template/config/running/{encoded_uuid}"
-        config = session.get_json(endpoint)
-        self.config = CiscoConfParse(config["config"].splitlines())
-        logger.debug(f"Template loaded from {device.hostname}.")
-        return self.config
-
-    def load_from_file(self, file: str) -> CiscoConfParse:
-        """Load CLI config from file.
-        Args:
-            file: The path of the file to be loaded.
-        Returns:
-            CiscoConfParse: Loaded template.
-        """
-        self.config = CiscoConfParse(file)
-        return self.config
-
-    def generate_payload(self) -> dict:
-        config_str = "\n".join(self.config.ioscfg)
-        payload = {
-            "templateName": self.template_name,
-            "templateDescription": self.template_description,
-            "deviceType": self.device_model,
-            "templateConfiguration": config_str,
-            "factoryDefault": False,
-            "configType": "file",
-        }
-        if self.device_model not in [
-            "vedge",
-            "vsmart",
-            "vmanage",
-            "vedge-cloud",
-        ]:
-            payload["cliType"] = "device"
-            payload["draftMode"] = False
-        return payload
-
-    def update(self, session: ManagerSession, id: str, config: CiscoConfParse) -> bool:
-        """Update an existing cli template.
-
-        Args:
-            session: logged in API client session
-            id: Template id to update.
-            config: Updated config.
-
-        Returns:
-            bool: True if update template is successful, otherwise - False.
-
-        """
-        self.config = config
-        config_str = "\n".join(self.config.ioscfg)
-        payload = {
-            "templateId": id,
-            "templateName": self.template_name,
-            "templateDescription": self.template_description,
-            "deviceType": self.device_model,
-            "templateConfiguration": config_str,
-            "factoryDefault": False,
-            "configType": "file",
-            "draftMode": False,
-        }
-        endpoint = f"/dataservice/template/device/{id}"
-        try:
-            session.put(url=endpoint, json=payload)
-        except HTTPError as error:
-            if error.response:
-                response = json.loads(error.response.text)["error"]
-                logger.error(f'Response message: {response["message"]}')
-                logger.error(f'Response details: {response["details"]}')
-            else:
-                logger.error("Response is None.")
-            return False
-        logger.info(f"Template with name: {self.template_name} - updated.")
-        return True
-
-    @staticmethod
-    def compare_template(
-        first: CiscoConfParse,
-        second: CiscoConfParse,
-        full: bool = False,
-        debug: bool = False,
-        ignored_lines: List[str] = [],
-    ) -> str:
-        """
-
-        Args:
-            first: First template for comparison.
-            second: Second template for comparison.
-            full: Return a full comparison if True, otherwise only the lines that differ.
-            debug: Adding debug to the logger. Defaults to False.
-            ignored_lines: List of configs statements to be excluded from comparison
-
-        Returns:
-            str: The compared templates.
-
-        Code    Meaning
-        '- '    line unique to sequence 1
-        '+ '    line unique to sequence 2
-        '  '    line common to both sequences
-        '? '    line not present in either input sequence
-
-        Example:
-        >>> a = "!\n  tacacs\n  server 192.168.1.1\n   vpn 2\n   secret-key a\n   auth-port 151\n exit".splitlines()
-        >>> b = "!\n  tacacs\n  server 192.168.1.1\n   vpn 3\n   secret-key a\n   auth-port 151\n exit".splitlines()
-        >>> a_conf = CiscoConfParse(a)
-        >>> b_conf = CiscoConfParse(b)
-        >>> compare = TemplateAPI.compare_template(a_conf, b_conf full=True)
-        >>> print(compare)
-          !
-            tacacs
-            server 192.168.1.1
-        -    vpn 2
-        ?        ^
-        +    vpn 3
-        ?        ^
-            secret-key a
-            auth-port 151
-        exit
-        """
-        for line in ignored_lines:
-            first.delete_lines(line)
-            second.delete_lines(line)
-        first_n = list(map(lambda x: x.strip() + "\n", first.ioscfg))
-        second_n = list(map(lambda x: x.strip() + "\n", second.ioscfg))
-        compare = list(Differ().compare(first_n, second_n))
-        if not full:
-            compare = [x for x in compare if x[0] in ["?", "-", "+"]]
-        if debug:
-            logger.debug("".join(compare))
-        return "".join(compare)
-
-    def compare_with_running(
-        self,
-        session,
-        template: CiscoConfParse,
-        device: Device,
-        debug: bool = False,
-        ignored_lines: List[str] = [],
-    ) -> str:
-        """The comparison of the config with the one running on the machine.
-
-        Args:
-            template: The template to compare.
-            device: The device on which to compare config.
-            full: Return a full comparison if True, otherwise only the lines that differ.
-            debug: Adding debug to the logger. Defaults to False.
-            ignored_lines: List of configs statements to be excluded from comparison
-
-        Returns:
-            str: The compared templates.
-
-        Example:
-        >>> a = "!\n  tacacs\n  server 192.168.1.1\n   vpn 512\n   secret-key a\n   auth-port 151\n exit".splitlines()
-        >>> a_conf = CiscoConfParse(a)
-        >>> device = DevicesAPI(API_SESSION).get(DeviceField.HOSTNAME, device_name)
-        >>> compare = TemplateAPI.compare_template(a_conf, device, full=True)
-        >>> print(compare)
-        .
-        .
-        .
-            zbfw-udp-idle-time    30
-           !
-          !
-        + !
-        +   tacacs
-        +   server 192.168.1.1
-        +    vpn vpn 512
-        +    secret-key a
-        +    auth-port 151
-        +  exit
-          omp
-           no shutdown
-           ecmp-limit       6
-        .
-        .
-        .
-        """
-        running_config = self.load_running(session, device)
-        return self.compare_template(running_config, template, debug=debug, ignored_lines=ignored_lines)

catalystwan/api/templates/device_template/device_template.py

@@ -1,189 +0,0 @@
-# Copyright 2023 Cisco Systems, Inc. and its affiliates
-
-from __future__ import annotations
-
-import logging
-from typing import TYPE_CHECKING, Any, Dict, List, Literal, Optional
-from uuid import UUID
-
-from pydantic import BaseModel, ConfigDict, Field, field_validator
-
-if TYPE_CHECKING:
-    from catalystwan.session import ManagerSession
-
-logger = logging.getLogger(__name__)
-
-
-TemplateType = Literal["file", "template"]  # file == cli, template == feature
-
-
-def str_to_uuid(s: str) -> Optional[UUID]:
-    try:
-        return UUID(s)
-    except ValueError:
-        return None
-
-
-class GeneralTemplate(BaseModel):
-    model_config = ConfigDict(arbitrary_types_allowed=True, populate_by_name=True)
-
-    name: str = Field(default="")
-
-    sub_templates: List[GeneralTemplate] = Field(
-        default=[], serialization_alias="subTemplates", validation_alias="subTemplates"
-    )
-    template_id: str = Field(default="", serialization_alias="templateId", validation_alias="templateId")
-    template_type: str = Field(default="", serialization_alias="templateType", validation_alias="templateType")
-
-
-class DeviceTemplate(BaseModel):
-    """
-    ## Example:
-
-    >>> templates = [
-            "default_system", # Cisco System
-            "default_logging", # Cisco Logging
-            "default_banner", # Banner
-        ]
-    >>> device_template = DeviceTemplate(
-            template_name="python",
-            template_description="python",
-            general_templates=templates
-        )
-    >>> session.api.templates.create(device_template)
-    """
-
-    model_config = ConfigDict(arbitrary_types_allowed=True, populate_by_name=True)
-
-    template_name: str = Field(serialization_alias="templateName", validation_alias="templateName")
-    template_description: str = Field(serialization_alias="templateDescription", validation_alias="templateDescription")
-    device_type: str = Field(serialization_alias="deviceType", validation_alias="deviceType")
-    device_role: str = Field(default="sdwan-edge", serialization_alias="deviceRole", validation_alias="deviceRole")
-    config_type: Optional[str] = Field(
-        default="template", serialization_alias="configType", validation_alias="configType"
-    )
-    factory_default: Optional[bool] = Field(
-        default=False, serialization_alias="factoryDefault", validation_alias="factoryDefault"
-    )
-    policy_id: str = Field(default="", serialization_alias="policyId", validation_alias="policyId")
-    feature_template_uid_range: Optional[List] = Field(
-        default=[], serialization_alias="featureTemplateUidRange", validation_alias="featureTemplateUidRange"
-    )
-
-    connection_preference_required: Optional[bool] = Field(
-        default=True,
-        serialization_alias="connectionPreferenceRequired",
-        validation_alias="connectionPreferenceRequired",
-    )
-    connection_preference: Optional[bool] = Field(
-        default=True, serialization_alias="connectionPreference", validation_alias="connectionPreference"
-    )
-
-    general_templates: List[GeneralTemplate] = Field(
-        default=[], serialization_alias="generalTemplates", validation_alias="generalTemplates"
-    )
-    security_policy_id: str = Field(
-        default="", serialization_alias="securityPolicyId", validation_alias="securityPolicyId"
-    )
-    voice_policy_id: Optional[str] = Field(
-        default=None, serialization_alias="voicePolicyId", validation_alias="voicePolicyId"
-    )
-    template_configuration_edited: Optional[str] = Field(
-        default=None, serialization_alias="templateConfigurationEdited", validation_alias="templateConfigurationEdited"
-    )
-    template_configuration: Optional[str] = Field(
-        default=None, serialization_alias="templateConfiguration", validation_alias="templateConfiguration"
-    )
-    rid: Optional[int] = Field(default=None, serialization_alias="@rid", validation_alias="@rid")
-    cli_type: Optional[str] = Field(default=None, serialization_alias="cliType", validation_alias="cliType")
-    copy_edited: Optional[bool] = Field(default=None, serialization_alias="copyEdited", validation_alias="copyEdited")
-
-    def get_security_policy_uuid(self) -> Optional[UUID]:
-        return str_to_uuid(self.security_policy_id)
-
-    def get_policy_uuid(self) -> Optional[UUID]:
-        return str_to_uuid(self.policy_id)
-
-    def get_voice_policy_uuid(self) -> Optional[UUID]:
-        if self.voice_policy_id is None:
-            return None
-        return str_to_uuid(self.voice_policy_id)
-
-    def has_any_policy(self) -> bool:
-        return any((self.policy_id, self.security_policy_id, self.voice_policy_id))
-
-    def generate_payload(self) -> str:
-        output = self.model_dump_json(by_alias=True)
-        return output
-
-    @field_validator("general_templates", mode="before")
-    @classmethod
-    def parse_templates(cls, value):
-        output = []
-        for template in value:
-            if isinstance(template, str):
-                output.append(GeneralTemplate(name=template))
-            else:
-                output.append(template)
-        return output
-
-    @classmethod
-    def get(self, name: str, session: ManagerSession) -> DeviceTemplate:
-        device_template = session.api.templates.get(DeviceTemplate).filter(name=name).single_or_default()
-        resp = session.get(f"dataservice/template/device/object/{device_template.id}").json()
-        return DeviceTemplate(**resp)
-
-    def associate_feature_template(self, template_type: str, template_uuid: UUID) -> None:
-        self.general_templates.append(
-            GeneralTemplate(name="", template_id=str(template_uuid), template_type=template_type)
-        )
-
-    def associate_security_policy(self, security_policy_uuid: UUID) -> None:
-        self.security_policy_id = str(security_policy_uuid)
-
-    def associate_policy(self, policy_uuid: UUID) -> None:
-        self.policy_id = str(policy_uuid)
-
-    model_config = ConfigDict(populate_by_name=True, use_enum_values=True)
-
-
-class DeviceSpecificValue(BaseModel):
-    property: str
-
-
-class DeviceTemplateConfigAttached(BaseModel):
-    model_config = ConfigDict(arbitrary_types_allowed=True, populate_by_name=True)
-    host_name: Optional[str] = Field(None, serialization_alias="host-name", validation_alias="host-name")
-    device_ip: Optional[str] = Field(None, serialization_alias="deviceIP", validation_alias="deviceIP")
-    local_system_ip: Optional[str] = Field(
-        None, serialization_alias="local-system-ip", validation_alias="local-system-ip"
-    )
-    site_id: Optional[str] = Field(None, serialization_alias="site-id", validation_alias="site-id")
-    device_groups: Optional[List[str]] = Field(
-        None, serialization_alias="device-groups", validation_alias="device-groups"
-    )
-    uuid: Optional[str] = Field(None, serialization_alias="uuid", validation_alias="uuid")
-    personality: Optional[str] = Field(None, serialization_alias="personality", validation_alias="personality")
-    config_cloudx_mode: Optional[str] = Field(
-        None, serialization_alias="configCloudxMode", validation_alias="configCloudxMode"
-    )
-
-
-class CreateDeviceInputPayload(BaseModel):
-    model_config = ConfigDict(populate_by_name=True)
-    template_id: str = Field(serialization_alias="templateId", validation_alias="templateId")
-    device_ids: List[str] = Field(serialization_alias="deviceIds", validation_alias="deviceIds")
-    is_edited: bool = Field(serialization_alias="isEdited", validation_alias="isEdited")
-    is_master_edited: bool = Field(serialization_alias="isMasterEdited", validation_alias="isMasterEdited")
-
-
-class DeviceInputValues(BaseModel):
-    model_config = ConfigDict(populate_by_name=True, extra="allow")
-    csv_device_ip: str = Field(validation_alias="csv-deviceIP", serialization_alias="csv-deviceIP")
-    csv_device_id: str = Field(validation_alias="csv-deviceId", serialization_alias="csv-deviceId")
-    csv_host_name: str = Field(validation_alias="csv-host-name", serialization_alias="csv-host-name")
-    csv_status: str = Field(validation_alias="csv-status", serialization_alias="csv-status")
-
-    @property
-    def values(self) -> Dict[str, Any]:
-        return self.__pydantic_extra__ or dict()

catalystwan/api/templates/device_variable.py

@@ -1,7 +0,0 @@
-# Copyright 2023 Cisco Systems, Inc. and its affiliates
-
-from pydantic import BaseModel
-
-
-class DeviceVariable(BaseModel):
-    name: str

catalystwan/api/templates/feature_template.py

@@ -1,133 +0,0 @@
-# Copyright 2023 Cisco Systems, Inc. and its affiliates
-
-from __future__ import annotations
-
-import json
-from abc import ABC, abstractmethod
-from pathlib import Path
-from typing import TYPE_CHECKING, Any, Dict, List, Union, cast
-
-from jinja2 import DebugUndefined, Environment, FileSystemLoader, meta  # type: ignore
-from pydantic import BaseModel, model_validator
-
-from catalystwan.api.templates.device_variable import DeviceVariable
-from catalystwan.models.common import DeviceModel
-from catalystwan.utils.dict import FlattenedDictValue, flatten_dict
-from catalystwan.utils.feature_template.find_template_values import find_template_values
-from catalystwan.utils.pydantic_field import get_extra_field
-
-if TYPE_CHECKING:
-    from catalystwan.session import ManagerSession
-
-
-class FeatureTemplateValidator(BaseModel, ABC):
-    @model_validator(mode="before")
-    @classmethod
-    def map_fields(cls, values: Union[Any, Dict[str, Union[List[FlattenedDictValue], Any]]]):
-        if not isinstance(values, dict):
-            return values
-        for field_name, field_info in cls.model_fields.items():
-            vmanage_key = get_extra_field(field_info, "vmanage_key")
-            if vmanage_key in values:
-                payload_name = vmanage_key
-            elif field_info.alias in values:
-                payload_name = field_info.alias
-            elif field_name in values:
-                payload_name = field_name
-            else:
-                continue
-            data_path = get_extra_field(field_info, "data_path", [])
-            value = values.pop(payload_name)
-            if value and isinstance(value, list) and all([isinstance(v, FlattenedDictValue) for v in value]):
-                for template_value in value:
-                    if template_value.data_path == data_path:
-                        values[field_name] = template_value.value
-                        break
-            else:
-                values[field_name] = value
-        return values
-
-
-class FeatureTemplate(FeatureTemplateValidator, ABC):
-    template_name: str
-    template_description: str
-    device_models: List[DeviceModel] = []
-    device_specific_variables: Dict[str, DeviceVariable] = {}
-
-    def generate_payload(self, session: ManagerSession) -> str:
-        env = Environment(
-            loader=FileSystemLoader(self.payload_path.parent),
-            trim_blocks=True,
-            lstrip_blocks=True,
-            undefined=DebugUndefined,
-        )
-        template = env.get_template(self.payload_path.name)
-        output = template.render(self.model_dump(mode="json"))
-
-        ast = env.parse(output)
-        if meta.find_undeclared_variables(ast):
-            print(meta.find_undeclared_variables(ast))
-            raise Exception
-        return output
-
-    def generate_cli(self) -> str:
-        raise NotImplementedError()
-
-    @property
-    @abstractmethod
-    def payload_path(self) -> Path:
-        raise NotImplementedError()
-
-    @property
-    def type(self) -> str:
-        raise NotImplementedError()
-
-    @model_validator(mode="before")
-    @classmethod
-    def remove_device_variables(cls, values):
-        if "device_specific_variables" not in values:
-            values["device_specific_variables"] = {}
-        to_delete = {}
-
-        # TODO: Add support for nested models with DeviceVariable
-        for key, value in values.items():
-            if isinstance(value, DeviceVariable):
-                to_delete[key] = value
-                field_key = cls.model_fields[key].json_schema_extra.get("vmanage_key", cls.model_fields[key].alias)
-                values["device_specific_variables"][field_key] = DeviceVariable(name=value.name)
-
-        for var in to_delete:
-            if var in values:
-                del values[var]
-
-        return values
-
-    @classmethod
-    def get(cls, session: ManagerSession, name: str) -> FeatureTemplate:
-        """Gets feature template model corresponding to existing feature template based on provided name
-
-        Args:
-            session: ManagerSession
-            name: name of the existing feature template
-
-        Returns:
-            FeatureTemplate: filed out feature template model
-        """
-        from catalystwan.utils.feature_template.choose_model import choose_model
-
-        template_info = (
-            session.api.templates._get_feature_templates(summary=False).filter(name=name).single_or_default()
-        )
-        template_definition_as_dict = json.loads(cast(str, template_info.template_definition))
-
-        feature_template_model = choose_model(type_value=template_info.template_type)
-
-        values_from_template_definition = find_template_values(template_definition_as_dict)
-        flattened_values = flatten_dict(values_from_template_definition)
-
-        return feature_template_model(
-            template_name=template_info.name,
-            template_description=template_info.description,
-            device_models=[model for model in template_info.device_type],
-            **flattened_values,
-        )