Merge branch 'main' into patch-upgrade-feature

.github/CODEOWNERS

@@ -4,4 +4,4 @@
 # These owners will be the default owners for everything in
 # the repo. Unless a later match takes precedence
 
-*       @kagrski @JimOverholt @igosoft @sbasan @bboot2
+*       @kagrski @JimOverholt @igosoft @sbasan @bboot2 @jkrajew

CONTRIBUTING.md

@@ -3,8 +3,7 @@
 We're really glad you want to help.
 
 ## Here are some important resources:
-
-  * Want to add something from yourself? [Make a PR](https://github.com/CiscoDevNet/catalystwan/pulls) - remember to follow code guidelines.
+  * Want to add something from yourself? [Make a PR](https://github.com/CiscoDevNet/catalystwan/pulls) - remember to follow [code guidelines](#code-guidelines).
     ### Contributors from CiscoDevNet organization:
     To make a PR - pull the repository, create branch for your changes, make said changes and make the pull request. Now just wait for the review and feedback from our developers.  
     ### Contributors outside CiscoDevNet organization

README.md

@@ -11,27 +11,89 @@ Cisco Catalyst WAN SDK is a package for creating simple and parallel automatic r
 pip install catalystwan
 ```
 
-## Session usage example
-Our session is an extension to `requests.Session` designed to make it easier to communicate via API calls with SDWAN Manager. We provide ready to use authentication, you have to simply provide the Manager url, username and password as as if you were doing it through a GUI. 
+## Manager Session
+In order to execute SDK APIs **ManagerSession** needs to be created. The fastest way to get started is to use `create_manager_session()` method which configures session, performs authentication for given credentials and returns **ManagerSession** instance in operational state. **ManagerSession** provides a collection of supported APIs in `api` instance variable.
+Please check example below:
+
 ```python
 from catalystwan.session import create_manager_session
 
 url = "example.com"
 username = "admin"
 password = "password123"
+
 with create_manager_session(url=url, username=username, password=password) as session:
-    session.get("/dataservice/device")
+    devices = session.api.devices.get()
+    print(devices)
+```
+**ManagerSession** extends [requests.Session](https://requests.readthedocs.io/en/latest/user/advanced/#session-objects) so all functionality from [requests](https://requests.readthedocs.io/en/latest/) library is avaiable to user, it also implements python [contextmanager](https://docs.python.org/3.8/library/contextlib.html#contextlib.contextmanager) and automatically frees server resources on exit.
+
+<details>
+    <summary> <b>Configure Manager Session before using</b> <i>(click to expand)</i></summary>
+
+It is possible to configure **ManagerSession** prior sending any request.
 
-# When interacting with the SDWAN Manager API without using a context manager, it's important 
-# to manually execute the `close()` method to release the user session resource.
+```python
+from catalystwan.session import ManagerSession
+
+url = "example.com"
+username = "admin"
+password = "password123"
 
-session = create_manager_session(url=url, username=username, password=password)
+# configure session using constructor - nothing will be sent to target server yet
+session = ManagerSession(url=url, username=username, password=password)
+# login and send requests
+session.login()
 session.get("/dataservice/device")
 session.close()
 ```
+When interacting with the SDWAN Manager API without using a context manager, it's important 
+to manually execute the `close()` method to release the user session resource.
 Ensure that the `close()` method is called after you have finished using the session to maintain optimal resource management and avoid potential errors.
 
+</details>
+
+<details>
+    <summary> <b>Login as Tenant</b> <i>(click to expand)</i></summary>
+
+Tenant domain needs to be provided in url together with Tenant credentials.
+
+```python
+from catalystwan.session import create_manager_session
+
+url = "tenant.example.com"
+username = "tenant_user"
+password = "password123"
+
+with create_manager_session(url=url, username=username, password=password) as session:
+    print(session.session_type)
+```
+
+</details>
+
+<details>
+    <summary> <b>Login as Provider-as-Tenant</b> <i>(click to expand)</i></summary>
+
+Tenant `subdomain` needs to be provided as additional argument together with Provider credentials.
+
+```python
+from catalystwan.session import create_manager_session
+
+url = "example.com"
+username = "provider"
+password = "password123"
+subdomain = "tenant.example.com"
+
+with create_manager_session(url=url, username=username, password=password, subdomain=subdomain) as session:
+    print(session.session_type)
+```
+
+</details>
+
+
+
 ## API usage examples
+All examples below assumes `session` variable contains logged-in [Manager Session](#Manager-Session) instance.
 
 <details>
     <summary> <b>Get devices</b> <i>(click to expand)</i></summary>
@@ -67,7 +129,8 @@ speedtest = session.api.speedtest.speedtest(devices[0], devices[1])
 
 ```python
 # Prepare devices list
-vsmarts = session.api.devices.get().filter(personality=Personality.VSMART)
+controllers = session.endpoints.configuration_device_inventory.get_device_details('controllers')
+vsmarts = controllers.filter(personality=Personality.VSMART)
 image = "viptela-20.7.2-x86_64.tar.gz"
 
 # Upload image

catalystwan/__init__.py

@@ -1,3 +1,5 @@
+# Copyright 2022 Cisco Systems, Inc. and its affiliates
+
 import logging
 import logging.config
 import multiprocessing
@@ -11,6 +13,8 @@
 
 import urllib3
 
+USER_AGENT = f"{__package__}/{metadata.version(__package__)}"
+
 
 def with_proc_info_header(method: Callable[..., str]) -> Callable[..., str]:
     """

catalystwan/abstractions.py

@@ -1,3 +1,5 @@
+# Copyright 2024 Cisco Systems, Inc. and its affiliates
+
 from typing import Optional, Protocol, Type, TypeVar
 
 from packaging.version import Version  # type: ignore

catalystwan/api/admin_tech_api.py

@@ -1,3 +1,5 @@
+# Copyright 2022 Cisco Systems, Inc. and its affiliates
+
 """
 Module for handling admintech logs for a device
 """

catalystwan/api/administration.py

@@ -1,3 +1,5 @@
+# Copyright 2022 Cisco Systems, Inc. and its affiliates
+
 from __future__ import annotations
 
 import logging

catalystwan/api/alarms_api.py

@@ -1,3 +1,5 @@
+# Copyright 2022 Cisco Systems, Inc. and its affiliates
+
 from __future__ import annotations
 
 import logging

catalystwan/api/api_container.py

@@ -1,3 +1,5 @@
+# Copyright 2023 Cisco Systems, Inc. and its affiliates
+
 from __future__ import annotations
 
 from typing import TYPE_CHECKING

catalystwan/api/basic_api.py

@@ -1,3 +1,5 @@
+# Copyright 2022 Cisco Systems, Inc. and its affiliates
+
 """Methods covering essential API endpoints and related data classes."""
 from __future__ import annotations
 

catalystwan/api/config_device_inventory_api.py

@@ -1,3 +1,5 @@
+# Copyright 2023 Cisco Systems, Inc. and its affiliates
+
 from __future__ import annotations
 
 from typing import TYPE_CHECKING

catalystwan/api/config_group_api.py

@@ -1,3 +1,5 @@
+# Copyright 2023 Cisco Systems, Inc. and its affiliates
+
 from __future__ import annotations
 
 from typing import TYPE_CHECKING

catalystwan/api/configuration_groups/parcel.py

@@ -1,3 +1,5 @@
+# Copyright 2023 Cisco Systems, Inc. and its affiliates
+
 from enum import Enum
 from typing import Any, Dict, Generic, Literal, Optional, TypeVar, get_origin
 

catalystwan/api/configuration_groups/parcels/cellular_controller.py

@@ -1,3 +1,5 @@
+# Copyright 2024 Cisco Systems, Inc. and its affiliates
+
 from enum import Enum
 from typing import Union
 

catalystwan/api/dashboard_api.py

@@ -1,3 +1,5 @@
+# Copyright 2023 Cisco Systems, Inc. and its affiliates
+
 from __future__ import annotations
 
 from typing import TYPE_CHECKING

catalystwan/api/device_action_api.py

@@ -1,3 +1,5 @@
+# Copyright 2022 Cisco Systems, Inc. and its affiliates
+
 from __future__ import annotations
 
 import logging

catalystwan/api/feature_profile_api.py

@@ -1,3 +1,5 @@
+# Copyright 2023 Cisco Systems, Inc. and its affiliates
+
 from __future__ import annotations
 
 from typing import TYPE_CHECKING, Any, Protocol, Type, Union, overload

catalystwan/api/logs_api.py

@@ -1,3 +1,5 @@
+# Copyright 2022 Cisco Systems, Inc. and its affiliates
+
 from __future__ import annotations
 
 import logging

catalystwan/api/monitoring_status_api.py

@@ -1,3 +1,5 @@
+# Copyright 2024 Cisco Systems, Inc. and its affiliates
+
 from __future__ import annotations
 
 import logging

catalystwan/api/mtt_aaa_api.py

@@ -1,3 +1,5 @@
+# Copyright 2023 Cisco Systems, Inc. and its affiliates
+
 from __future__ import annotations
 
 import logging

catalystwan/api/omp_api.py

@@ -1,3 +1,5 @@
+# Copyright 2022 Cisco Systems, Inc. and its affiliates
+
 from __future__ import annotations
 
 from typing import TYPE_CHECKING, List

catalystwan/api/packet_capture_api.py

@@ -1,3 +1,5 @@
+# Copyright 2022 Cisco Systems, Inc. and its affiliates
+
 from __future__ import annotations
 
 import logging

catalystwan/api/parcel_api.py

@@ -1,3 +1,5 @@
+# Copyright 2023 Cisco Systems, Inc. and its affiliates
+
 from __future__ import annotations
 
 from typing import TYPE_CHECKING, Protocol

catalystwan/api/partition_manager_api.py

@@ -1,16 +1,18 @@
+# Copyright 2023 Cisco Systems, Inc. and its affiliates
+
 from __future__ import annotations
 
 import logging
 from typing import TYPE_CHECKING, List, Optional, cast
 
 from catalystwan.api.task_status_api import Task
 from catalystwan.api.versions_utils import DeviceVersions, RepositoryAPI
-from catalystwan.dataclasses import Device
 from catalystwan.endpoints.configuration_device_actions import (
     PartitionActionPayload,
     RemovePartitionActionPayload,
     RemovePartitionDevice,
 )
+from catalystwan.endpoints.configuration_device_inventory import DeviceDetailsResponse
 from catalystwan.exceptions import EmptyVersionPayloadError
 from catalystwan.typed_list import DataSequence
 from catalystwan.utils.upgrades_helper import get_install_specification, validate_personality_homogeneity
@@ -48,7 +50,9 @@ def __init__(self, session: ManagerSession) -> None:
         self.repository = RepositoryAPI(self.session)
         self.device_version = DeviceVersions(self.session)
 
-    def set_default_partition(self, devices: DataSequence[Device], partition: Optional[str] = None) -> Task:
+    def set_default_partition(
+        self, devices: DataSequence[DeviceDetailsResponse], partition: Optional[str] = None
+    ) -> Task:
         """
         Set default software versions for devices
 
@@ -82,7 +86,7 @@ def set_default_partition(self, devices: DataSequence[Device], partition: Option
         return Task(self.session, partition_action.id)
 
     def remove_partition(
-        self, devices: DataSequence[Device], partition: Optional[str] = None, force: bool = False
+        self, devices: DataSequence[DeviceDetailsResponse], partition: Optional[str] = None, force: bool = False
     ) -> Task:
         """
         Remove chosen software version from device

catalystwan/api/policy_api.py

@@ -1,3 +1,5 @@
+# Copyright 2023 Cisco Systems, Inc. and its affiliates
+
 from __future__ import annotations
 
 from typing import TYPE_CHECKING, Any, Dict, List, Mapping, Optional, Type, overload
@@ -122,13 +124,13 @@
 from catalystwan.endpoints.configuration.policy.list.site import ConfigurationPolicySiteList, SiteListInfo
 from catalystwan.endpoints.configuration.policy.list.sla import ConfigurationPolicySLAClassList, SLAClassListInfo
 from catalystwan.endpoints.configuration.policy.list.tloc import ConfigurationPolicyTLOCList, TLOCListInfo
-from catalystwan.endpoints.configuration.policy.list.url_black_list import (
-    ConfigurationPolicyURLBlackList,
-    URLBlackListInfo,
+from catalystwan.endpoints.configuration.policy.list.url_allow_list import (
+    ConfigurationPolicyURLAllowList,
+    URLAllowListInfo,
 )
-from catalystwan.endpoints.configuration.policy.list.url_white_list import (
-    ConfigurationPolicyURLWhiteList,
-    URLWhiteListInfo,
+from catalystwan.endpoints.configuration.policy.list.url_block_list import (
+    ConfigurationPolicyURLBlockList,
+    URLBlockListInfo,
 )
 from catalystwan.endpoints.configuration.policy.list.vpn import ConfigurationPolicyVPNList, VPNListInfo
 from catalystwan.endpoints.configuration.policy.list.zone import ConfigurationPolicyZoneList, ZoneListInfo
@@ -181,8 +183,8 @@
     SiteList,
     SLAClassList,
     TLOCList,
-    URLBlackList,
-    URLWhiteList,
+    URLAllowList,
+    URLBlockList,
     VPNList,
     ZoneList,
 )
@@ -238,8 +240,8 @@
     SiteList: ConfigurationPolicySiteList,
     SLAClassList: ConfigurationPolicySLAClassList,
     TLOCList: ConfigurationPolicyTLOCList,
-    URLBlackList: ConfigurationPolicyURLBlackList,
-    URLWhiteList: ConfigurationPolicyURLWhiteList,
+    URLBlockList: ConfigurationPolicyURLBlockList,
+    URLAllowList: ConfigurationPolicyURLAllowList,
     VPNList: ConfigurationPolicyVPNList,
     ZoneList: ConfigurationPolicyZoneList,
 }
@@ -498,11 +500,11 @@ def get(self, type: Type[TLOCList]) -> DataSequence[TLOCListInfo]:
         ...
 
     @overload
-    def get(self, type: Type[URLBlackList]) -> DataSequence[URLBlackListInfo]:
+    def get(self, type: Type[URLBlockList]) -> DataSequence[URLBlockListInfo]:
         ...
 
     @overload
-    def get(self, type: Type[URLWhiteList]) -> DataSequence[URLWhiteListInfo]:
+    def get(self, type: Type[URLAllowList]) -> DataSequence[URLAllowListInfo]:
         ...
 
     @overload
@@ -616,11 +618,11 @@ def get(self, type: Type[TLOCList], id: UUID) -> TLOCListInfo:
         ...
 
     @overload
-    def get(self, type: Type[URLBlackList], id: UUID) -> URLBlackListInfo:
+    def get(self, type: Type[URLBlockList], id: UUID) -> URLBlockListInfo:
         ...
 
     @overload
-    def get(self, type: Type[URLWhiteList], id: UUID) -> URLWhiteListInfo:
+    def get(self, type: Type[URLAllowList], id: UUID) -> URLAllowListInfo:
         ...
 
     @overload

catalystwan/api/resource_pool_api.py

@@ -1,3 +1,5 @@
+# Copyright 2023 Cisco Systems, Inc. and its affiliates
+
 from __future__ import annotations
 
 import logging