catalystwan 0.40.1.dev7__py3-none-any.whl → 2.0.0a0__py3-none-any.whl

catalystwan/core/__init__.py

@@ -0,0 +1,2 @@
+from catalystwan.core.client import create_client as create_client
+from catalystwan.core.client import create_thread_client as create_thread_client

catalystwan/core/abstractions.py

@@ -0,0 +1,26 @@
+from typing import Optional, Protocol, TypeVar
+
+from catalystwan.abc import SessionInterface, SessionType
+from requests import PreparedRequest  # type: ignore
+
+T = TypeVar("T")
+
+
+ProviderView = SessionType.PROVIDER
+TenantView = SessionType.TENANT
+ProviderAsTenantView = SessionType.PROVIDER_AS_TENANT
+SingleTenantView = SessionType.SINGLE_TENANT
+
+
+class AuthProtocol(Protocol):
+    """
+    Additional interface for Auth to handle login/logout for multiple auth types by common ManagerSession
+    """
+
+    def logout(self, client: SessionInterface) -> None: ...
+
+    def clear(self, last_request: Optional[PreparedRequest]) -> None: ...
+
+    def increase_session_count(self) -> None: ...
+
+    def decrease_session_count(self) -> None: ...

catalystwan/{apigw_auth.py → core/apigw_auth.py}

@@ -1,22 +1,22 @@
-# Copyright 2024 Cisco Systems, Inc. and its affiliates
 import logging
+from dataclasses import asdict, dataclass, field
 from threading import RLock
 from typing import Literal, Optional
 from urllib.parse import urlparse
 
-from pydantic import BaseModel, Field, PositiveInt
+from catalystwan.abc import SessionInterface
+from catalystwan.core.abstractions import AuthProtocol
+from catalystwan.core.exceptions import CatalystwanException
+from catalystwan.core.response import auth_response_debug
 from requests import HTTPError, PreparedRequest, post
 from requests.auth import AuthBase
 from requests.exceptions import JSONDecodeError
 
-from catalystwan.abstractions import APIEndpointClient, AuthProtocol
-from catalystwan.exceptions import CatalystwanException
-from catalystwan.response import auth_response_debug
-
 LoginMode = Literal["machine", "user", "session"]
 
 
-class ApiGwLogin(BaseModel):
+@dataclass
+class ApiGwLogin:
     client_id: str
     client_secret: str
     org_name: str
@@ -24,7 +24,7 @@ class ApiGwLogin(BaseModel):
     username: Optional[str] = None
     session: Optional[str] = None
     tenant_user: Optional[bool] = None
-    token_duration: PositiveInt = Field(default=10, description="in minutes")
+    token_duration: int = field(default=10)
 
 
 class ApiGwAuth(AuthBase, AuthProtocol):
@@ -34,7 +34,12 @@ class ApiGwAuth(AuthBase, AuthProtocol):
     2. Use the token in the Authorization header for subsequent requests.
     """
 
-    def __init__(self, login: ApiGwLogin, logger: Optional[logging.Logger] = None, verify: bool = False):
+    def __init__(
+        self,
+        login: ApiGwLogin,
+        logger: Optional[logging.Logger] = None,
+        verify: bool = False,
+    ):
         self.login = login
         self.token = ""
         self.logger = logger or logging.getLogger(__name__)
@@ -70,13 +75,19 @@ class ApiGwAuth(AuthBase, AuthProtocol):
 
     @staticmethod
     def get_token(
-        base_url: str, apigw_login: ApiGwLogin, logger: Optional[logging.Logger] = None, verify: bool = False
+        base_url: str,
+        apigw_login: ApiGwLogin,
+        logger: Optional[logging.Logger] = None,
+        verify: bool = False,
     ) -> str:
         try:
             response = post(
                 url=f"{base_url}/apigw/login",
                 verify=verify,
-                json=apigw_login.model_dump(exclude_none=True),
+                json=asdict(
+                    apigw_login,
+                    dict_factory=lambda d: {k: v for (k, v) in d if v is not None},
+                ),
                 timeout=10,
             )
             if logger is not None:
@@ -84,9 +95,13 @@ class ApiGwAuth(AuthBase, AuthProtocol):
             response.raise_for_status()
             token = response.json()["token"]
         except JSONDecodeError:
-            raise CatalystwanException(f"Incorrect response type from ApiGateway login request, ({response.text})")
+            raise CatalystwanException(
+                f"Incorrect response type from ApiGateway login request, ({response.text})"
+            )
         except HTTPError as ex:
-            raise CatalystwanException(f"Problem with connection to ApiGateway login endpoint, ({ex})")
+            raise CatalystwanException(
+                f"Problem with connection to ApiGateway login endpoint, ({ex})"
+            )
         except KeyError as ex:
             raise CatalystwanException(f"Not found token in login response from ApiGateway, ({ex})")
         else:
@@ -94,7 +109,7 @@ class ApiGwAuth(AuthBase, AuthProtocol):
                 raise CatalystwanException("Failed to get bearer token")
         return token
 
-    def logout(self, client: APIEndpointClient) -> None:
+    def logout(self, client: SessionInterface) -> None:
         return None
 
     def _clear(self) -> None:

catalystwan/core/client.py

@@ -0,0 +1,71 @@
+from __future__ import annotations
+
+import logging
+from contextlib import contextmanager
+from copy import copy
+from typing import TYPE_CHECKING, Generator, Optional, Union
+
+from catalystwan.core.apigw_auth import ApiGwAuth
+from catalystwan.core.loader import load_client
+from catalystwan.core.request_adapter import RequestAdapter
+from catalystwan.core.request_limiter import RequestLimiter
+from catalystwan.core.session import ManagerSession, create_base_url, create_manager_session
+from catalystwan.core.vmanage_auth import vManageAuth
+
+if TYPE_CHECKING:
+    from catalystwan.core.loader import ApiClient
+
+
+@contextmanager
+def create_thread_client(
+    url: str,
+    auth: Union[vManageAuth, ApiGwAuth],
+    port: Optional[int] = None,
+    subdomain: Optional[str] = None,
+    logger: Optional[logging.Logger] = None,
+    request_limiter: Optional[RequestLimiter] = None,
+) -> Generator[ApiClient, None, None]:
+    if logger is None:
+        logger = logging.getLogger(__name__)
+    session = ManagerSession(
+        base_url=create_base_url(url, port),
+        auth=auth,
+        subdomain=subdomain,
+        logger=logger,
+        request_limiter=request_limiter,
+    )
+    with session.login():
+        version = session.api_version.base_version
+        logger.debug(f"Choosing client for version {version}...")
+        client = load_client(session.api_version.base_version)
+        logger.debug(f"Client for version {version} loaded")
+        yield client(RequestAdapter(session=session, logger=logger))
+
+
+@contextmanager
+def create_client(
+    url: str,
+    username: str,
+    password: str,
+    port: Optional[int] = None,
+    subdomain: Optional[str] = None,
+    logger: Optional[logging.Logger] = None,
+) -> Generator[ApiClient, None, None]:
+    if logger is None:
+        logger = logging.getLogger(__name__)
+    with create_manager_session(url, username, password, port, subdomain, logger) as session:
+        version = session.api_version.base_version
+        logger.debug(f"Choosing client for version {version}...")
+        client = load_client(session.api_version.base_version)
+        logger.debug(f"Client for version {version} loaded")
+        yield client(RequestAdapter(session=session, logger=logger))
+
+
+@contextmanager
+def copy_client(client: ApiClient) -> Generator[ApiClient, None, None]:
+    request_adapter = copy(client._request_adapter)
+    session = request_adapter.session
+    with session.login():
+        new_client = load_client(session.api_version.base_version)(request_adapter)
+        assert new_client.api_version == client.api_version
+        yield new_client

catalystwan/core/encoder.py

@@ -0,0 +1,12 @@
+import json
+from typing import Any
+
+
+def serialize_model_value(value: Any, to_json: bool) -> Any:
+    if not to_json:
+        return value
+    try:
+        json.dumps(value)
+        return value
+    except TypeError:
+        return str(value)

catalystwan/{exceptions.py → core/exceptions.py}

@@ -1,15 +1,15 @@
-# Copyright 2023 Cisco Systems, Inc. and its affiliates
-
+from dataclasses import dataclass
 from typing import Union
 
-from pydantic import BaseModel
 from requests import HTTPError, RequestException
 
 
-class ManagerErrorInfo(BaseModel):
-    message: Union[str, None] = None
-    details: Union[str, None] = None
-    code: Union[str, None] = None
+@dataclass
+class ManagerErrorInfo:
+    message: Union[str, None]
+    details: Union[str, None]
+    code: Union[str, None]
+    type: Union[str, None]
 
 
 class CatalystwanException(Exception):
@@ -19,6 +19,10 @@ class CatalystwanException(Exception):
 class ManagerRequestException(RequestException, CatalystwanException):
     """Exception raised when there is ambigous problem during sending of request to Manager"""
 
+    def __init__(self, *args, **kwargs):
+        """Initialize RequestException with `request` and `response` objects."""
+        super().__init__(*args, **kwargs)
+
 
 class ManagerHTTPError(HTTPError, ManagerRequestException):
     def __init__(self, *args, error_info: ManagerErrorInfo, **kwargs):
@@ -39,7 +43,9 @@ class ManagerHTTPError(HTTPError, ManagerRequestException):
             f"Headers: {self.request.headers}, Body: {self.request.body}"
         )
         response_str = (
-            f"Response: {str(self.response.json())}" if self.response else "Response: No response information"
+            f"Response: {str(self.response.json())}"
+            if self.response
+            else "Response: No response information"
         )
         return f"{error_info_str}\n\n {request_str}\n\n {response_str}"
 
@@ -114,7 +120,9 @@ class APIVersionError(CatalystwanException):
     """Raised when API is unsupported in running vManage version."""
 
     def __init__(self, item, supported, current):
-        self.message = f"vManage is running: {current} but {item} only supported in API version: {supported}"
+        self.message = (
+            f"vManage is running: {current} but {item} only supported in API version: {supported}"
+        )
 
 
 class APIViewError(CatalystwanException):
@@ -210,3 +218,15 @@ class CatalystwanDeprecationWarning(DeprecationWarning):
             f" The public API SHOULD NOT be considered stable."
         )
         return message
+
+
+class CatalystwanModelInputException(CatalystwanException): ...
+
+
+class CatalystwanModelValidationError(CatalystwanException): ...
+
+
+class CatalystwanResponseTypeError(CatalystwanException):
+    """Raised when SDWAN response does not match expected type."""
+
+    ...

catalystwan/core/loader.py

@@ -0,0 +1,37 @@
+# This file is autogenerated and cannot be modified manually.
+
+from __future__ import annotations
+
+import typing as t
+
+if t.TYPE_CHECKING:
+    from catalystwan.versions.v20_15.api_client import ApiClient as ApiClientV20_15
+    from catalystwan.versions.v20_16.api_client import ApiClient as ApiClientV20_16
+
+    ApiClient = t.Union[ApiClientV20_15, ApiClientV20_16]
+
+VERSIONS = ["20.15", "20.16"]
+
+
+@t.overload
+def load_client(version: t.Literal["20.15"]) -> t.Type[ApiClientV20_15]: ...
+
+
+@t.overload
+def load_client(version: t.Literal["20.16"]) -> t.Type[ApiClientV20_16]: ...
+
+
+@t.overload
+def load_client(version: str) -> t.Type[t.Union[ApiClientV20_15, ApiClientV20_16]]: ...
+
+
+def load_client(version: t.Union[str, t.Literal["20.15", "20.16"]]) -> t.Type[ApiClient]:
+    if version == "20.15":
+        from catalystwan.versions.v20_15.api_client import ApiClient as ApiClientV20_15
+
+        return ApiClientV20_15
+    if version == "20.16":
+        from catalystwan.versions.v20_16.api_client import ApiClient as ApiClientV20_16
+
+        return ApiClientV20_16
+    raise RuntimeError("Unsupported version: {}".format(version))

catalystwan/{__init__.py → core/metadata.py}

@@ -1,20 +1,14 @@
-# Copyright 2022 Cisco Systems, Inc. and its affiliates
-
-import logging
-import logging.config
 import multiprocessing
 from functools import lru_cache, wraps
 from importlib import metadata
 from importlib.machinery import PathFinder
-from os import environ
 from pathlib import Path
 from traceback import FrameSummary, StackSummary, extract_stack
-from typing import Callable, Final, List, Optional
-
-import urllib3
+from typing import Callable, List, Optional
 
-PACKAGE_VERSION = metadata.version(__package__)
-USER_AGENT = f"{__package__}/{PACKAGE_VERSION}"
+PACKAGE_NAME = "catalystwan"
+PACKAGE_VERSION = metadata.version(PACKAGE_NAME)
+USER_AGENT = f"{PACKAGE_NAME}/{PACKAGE_VERSION}"
 
 
 def with_proc_info_header(method: Callable[..., str]) -> Callable[..., str]:
@@ -59,25 +53,18 @@ def is_file_in_package(fname: str) -> bool:
     return Path(fname) in pkg_src_list
 
 
-def list_package_sources() -> List[Path]:
+def list_package_sources(package: Optional[str] = None) -> List[Path]:
     """
     Creates a list containing paths to all python source files
     for current package
     """
+    if package is None:
+        package = __package__
     pkg_srcs: List[Path] = []
-    if pkg_spec := PathFinder.find_spec(__package__):
+    if pkg_spec := PathFinder.find_spec(package):
         if pkg_origin := pkg_spec.origin:
             pkg_srcs = list(Path(pkg_origin).parent.glob("**/*.py"))
     return pkg_srcs
 
 
-LOGGING_CONF_DIR: Final[str] = str(Path(__file__).parents[0] / "logging.conf")
-__version__ = metadata.version(__package__)
-pkg_src_list = list_package_sources()
-
-
-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_logger.debug(f"catalystwan {__version__}")
+pkg_src_list = list_package_sources(PACKAGE_NAME)

catalystwan/core/models/deserialize.py

@@ -0,0 +1,203 @@
+from collections import deque
+from copy import deepcopy
+from dataclasses import fields, is_dataclass
+from functools import reduce
+from inspect import isclass, unwrap
+from typing import Any, Dict, List, Literal, Protocol, Tuple, Type, TypeVar, Union
+
+from catalystwan.core.exceptions import (
+    CatalystwanModelInputException,
+    CatalystwanModelValidationError,
+)
+from catalystwan.core.types import MODEL_TYPES, AliasPath, DataclassInstance
+from typing_extensions import Annotated, get_args, get_origin, get_type_hints
+
+T = TypeVar("T", bound=DataclassInstance)
+
+
+class ValueExtractorCallable(Protocol):
+    def __call__(self, field_value: Any) -> Any: ...
+
+
+class ModelDeserializer:
+    def __init__(self, model: Type[T]) -> None:
+        self.model = model
+        try:
+            self.model_type: MODEL_TYPES = model._catalystwan_model_type  # type: ignore[attr-defined]
+        except AttributeError:
+            self.model_type = "base"
+        self._exceptions: List[
+            Union[CatalystwanModelInputException, CatalystwanModelValidationError]
+        ] = []
+        # different models wrap their values in different ways, hence
+        # the need for multiple extractors
+        self.VALUE_EXTRACTORS: Dict[MODEL_TYPES, ValueExtractorCallable] = {
+            "base": self.__value_extractor_base,
+            "feature_template": self.__value_extractor_ft,
+            "parcel": self.__value_extractor_parcel,
+        }
+
+    def deserialize(self, *args, **kwargs) -> Tuple[List[Any], Dict[str, Any]]:
+        new_args, new_kwargs = self.__transform_model_input(
+            self.model, self.__value_extractor, *args, **kwargs
+        )
+        # Input errors are aggregated and thrown out as a bundle
+        self.__check_errors()
+        return new_args, new_kwargs
+
+    def __check_errors(self):
+        if self._exceptions:
+            # Put exceptions from current model first
+            self._exceptions.sort(key=lambda x: isinstance(x, CatalystwanModelValidationError))
+            current_model_errors = sum(
+                isinstance(x, CatalystwanModelInputException) for x in self._exceptions
+            )
+            message = f"{current_model_errors} validation errors for {self.model.__name__}\n"
+            for exc in self._exceptions:
+                message += f"{exc}\n"
+            raise CatalystwanModelValidationError(message)
+
+    def __is_optional(self, t: Any) -> bool:
+        if get_origin(t) is Union and type(None) in get_args(t):
+            return True
+        return False
+
+    def __extract_type(self, field_type: Any, field_value: Any, field_name: str) -> Any:
+        origin = get_origin(field_type)
+        # check for simple types and classes
+        if origin is None:
+            if field_type is Any:
+                return field_value
+            if isinstance(field_value, field_type):
+                return field_value
+            elif is_dataclass(field_type):
+                assert isinstance(field_type, type)
+                return deserialize(field_type, **field_value)
+            elif isclass(unwrap(field_type)):
+                if isinstance(field_value, dict):
+                    return field_type(**field_value)
+                else:
+                    try:
+                        return field_type(field_value)
+                    except ValueError:
+                        raise CatalystwanModelInputException(
+                            f"Unable to match or cast input value for {field_name} [expected_type={unwrap(field_type)}, input={field_value}, input_type={type(field_value)}]"
+                        )
+        elif origin is list:
+            if isinstance(field_value, list):
+                return [
+                    self.__extract_type(get_args(field_type)[0], value, field_name)
+                    for value in field_value
+                ]
+        elif self.__is_optional(field_type):
+            if field_value is None:
+                return None
+            else:
+                try:
+                    return self.__extract_type(get_args(field_type)[0], field_value, field_name)
+                except CatalystwanModelInputException as e:
+                    if not field_value:
+                        return None
+                    raise e
+        elif origin is Literal:
+            for arg in get_args(field_type):
+                try:
+                    if type(arg)(field_value) == arg:
+                        return type(arg)(field_value)
+                except Exception:
+                    continue
+        elif origin is Annotated:
+            validator, caster = field_type.__metadata__
+            if validator(field_value):
+                return field_value
+            return caster(field_value)
+        # TODO: Currently, casting is done left-to-right. Searching deeper for a better match may be the way to go.
+        elif origin is Union:
+            for arg in get_args(field_type):
+                try:
+                    return self.__extract_type(arg, field_value, field_name)
+                except Exception:
+                    continue
+        # Correct type not found, add exception
+        raise CatalystwanModelInputException(
+            f"Unable to match or cast input value for {field_name} [expected_type={unwrap(field_type)}, input={field_value}, input_type={type(field_value)}]"
+        )
+
+    def __transform_model_input(
+        self, cls: Type[T], value_extractor: ValueExtractorCallable, *args, **kwargs
+    ):
+        args_copy = deque(deepcopy(args))
+        kwargs_copy = deepcopy(kwargs)
+        new_args = []
+        new_kwargs = {}
+        field_types = get_type_hints(cls)
+        for field in fields(cls):
+            if not field.init:
+                continue
+            field_type = field_types[field.name]
+            # check args first
+            if len(args_copy) > 0:
+                field_value = args_copy.popleft()
+                try:
+                    new_args.append(
+                        self.__extract_type(field_type, value_extractor(field_value), field.name)
+                    )
+                except (
+                    CatalystwanModelInputException,
+                    CatalystwanModelValidationError,
+                ) as e:
+                    self._exceptions.append(e)
+                continue
+
+            alias = field.metadata.get("alias", None)
+            alias_path = alias if isinstance(alias, AliasPath) else [alias]
+            try:
+                # get value from given dict path
+                field_value = reduce(dict.get, alias_path, kwargs_copy)  # type: ignore[arg-type]
+            except TypeError:
+                field_value = None
+            if field_value is None:
+                if field.name in kwargs_copy:
+                    field_value = kwargs_copy[field.name]
+                else:
+                    continue
+            try:
+                new_kwargs[field.name] = self.__extract_type(
+                    field_type, value_extractor(field_value), field.name
+                )
+            except (
+                CatalystwanModelInputException,
+                CatalystwanModelValidationError,
+            ) as e:
+                self._exceptions.append(e)
+        return new_args, new_kwargs
+
+    @property
+    def __value_extractor(self) -> ValueExtractorCallable:
+        return self.VALUE_EXTRACTORS[self.model_type]
+
+    def __value_extractor_base(self, field_value: Any) -> Any:
+        return field_value
+
+    def __value_extractor_ft(self, field_value: Any) -> Any:
+        if isinstance(field_value, dict):
+            if "vipType" in field_value and field_value["vipType"] == "ignore":
+                return None
+            if "vipValue" in field_value:
+                return field_value["vipValue"]
+        return field_value
+
+    def __value_extractor_parcel(self, field_value: Any) -> Any:
+        if (
+            isinstance(field_value, dict)
+            and "option_type" in field_value
+            and "value" in field_value
+        ):
+            return field_value["value"]
+        return field_value
+
+
+def deserialize(catalystwan_model: Type[T], *args, **kwargs) -> T:
+    new_args, new_kwargs = ModelDeserializer(catalystwan_model).deserialize(*args, **kwargs)
+
+    return catalystwan_model(*new_args, **new_kwargs)