acex-devkit 1.2.0__tar.gz → 1.3.0__tar.gz

{acex_devkit-1.2.0 → acex_devkit-1.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: acex-devkit
-Version: 1.2.0
+Version: 1.3.0
 Summary: ACE-X DevKit - Development kit for building ACE-X drivers and plugins
 License: AGPL-3.0
 Keywords: automation,devkit,sdk,drivers,plugins

{acex_devkit-1.2.0 → acex_devkit-1.3.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "acex-devkit"
-version = "1.2.0"
+version = "1.3.0"
 description = "ACE-X DevKit - Development kit for building ACE-X drivers and plugins"
 authors = ["Johan Lahti <johan.lahti@acebit.se>"]
 readme = "README.md"

acex_devkit-1.3.0/src/acex_devkit/configdiffer/configdiffer.py

@@ -0,0 +1,158 @@
+from pydantic import BaseModel
+from typing import Any, Dict, List, Optional, get_origin, get_args
+
+from acex_devkit.models.composed_configuration import ComposedConfiguration
+from acex_devkit.models.attribute_value import AttributeValue
+from acex_devkit.configdiffer.diff import Diff, ComponentChange, AttributeChange, ComponentDiffOp
+
+
+class ConfigDiffer:
+
+    def _is_dict_of_models(self, annotation) -> bool:
+        """Check if a type annotation is Dict[str, SomeBaseModel]."""
+        origin = get_origin(annotation)
+        if origin is dict:
+            args = get_args(annotation)
+            if len(args) == 2 and isinstance(args[1], type) and issubclass(args[1], BaseModel):
+                return True
+        return False
+
+    def _is_base_model(self, annotation) -> bool:
+        """Check if a type annotation is a BaseModel subclass (not Dict, not AttributeValue)."""
+        return (
+            isinstance(annotation, type)
+            and issubclass(annotation, BaseModel)
+            and not issubclass(annotation, AttributeValue)
+        )
+
+    def _unwrap_optional(self, annotation):
+        """Unwrap Optional[X] to X. Returns the annotation unchanged if not Optional."""
+        origin = get_origin(annotation)
+        if origin is type(None):
+            return annotation
+        args = get_args(annotation)
+        if args:
+            # Optional[X] is Union[X, None]
+            non_none = [a for a in args if a is not type(None)]
+            if len(non_none) == 1:
+                return non_none[0]
+        return annotation
+
+    def _flatten(self, model: BaseModel, path: tuple = ()) -> Dict[tuple, BaseModel]:
+        """
+        Recursively walk a Pydantic model using type annotations to find
+        all components. Returns a flat mapping of path → model instance.
+
+        Rules:
+        - Dict[str, BaseModel] → component collection, each entry is a leaf
+        - BaseModel (not in Dict) → container, recurse deeper
+        - AttributeValue / primitives / None → skip (attributes, not components)
+        """
+        result = {}
+
+        for field_name, field_info in model.model_fields.items():
+            annotation = self._unwrap_optional(field_info.annotation)
+            value = getattr(model, field_name)
+
+            if value is None:
+                continue
+
+            if self._is_dict_of_models(annotation):
+                # Component collection: each entry is a diffable component
+                for key, component in value.items():
+                    component_path = path + (field_name, key)
+                    result[component_path] = component
+
+            elif self._is_base_model(annotation):
+                # Recurse deeper — if nothing found, this model itself is a leaf component
+                child_path = path + (field_name,)
+                deeper = self._flatten(value, child_path)
+                if deeper:
+                    result.update(deeper)
+                else:
+                    result[child_path] = value
+
+        return result
+
+    def _attribute_changes(self, before: BaseModel, after: BaseModel) -> List[AttributeChange]:
+        """
+        Compare two component model instances and return a list of changed attributes.
+        """
+        changes = []
+        all_fields = set(before.model_fields.keys()) | set(after.model_fields.keys())
+
+        for field_name in all_fields:
+            b = getattr(before, field_name, None)
+            a = getattr(after, field_name, None)
+            if b != a:
+                changes.append(AttributeChange(attribute_name=field_name, before=b, after=a))
+
+        return changes
+
+    def diff(self, *, desired_config: ComposedConfiguration, observed_config: ComposedConfiguration) -> Diff:
+        """
+        Compare two ComposedConfiguration objects and return a component-based diff.
+
+        Uses Pydantic model introspection to find all components (entries in
+        Dict[str, BaseModel] fields). Components are identified by their full
+        path, e.g. ('interfaces', 'GigabitEthernet0/0/1').
+        """
+        flat_desired = self._flatten(desired_config)
+        flat_observed = self._flatten(observed_config)
+
+        desired_paths = set(flat_desired.keys())
+        observed_paths = set(flat_observed.keys())
+
+        added = []
+        removed = []
+        changed = []
+
+        for path in desired_paths - observed_paths:
+            obj = flat_desired[path]
+            added.append(ComponentChange(
+                op=ComponentDiffOp.ADD,
+                path=list(path),
+                component_type=type(obj),
+                component_name=path[-1],
+                before=None,
+                after=obj,
+                before_dict=None,
+                after_dict=obj.model_dump(),
+            ))
+
+        for path in observed_paths - desired_paths:
+            obj = flat_observed[path]
+            removed.append(ComponentChange(
+                op=ComponentDiffOp.REMOVE,
+                path=list(path),
+                component_type=type(obj),
+                component_name=path[-1],
+                before=obj,
+                after=None,
+                before_dict=obj.model_dump(),
+                after_dict=None,
+            ))
+
+        for path in desired_paths & observed_paths:
+            desired_obj = flat_desired[path]
+            observed_obj = flat_observed[path]
+            if desired_obj != observed_obj:
+                changed.append(ComponentChange(
+                    op=ComponentDiffOp.CHANGE,
+                    path=list(path),
+                    component_type=type(desired_obj),
+                    component_name=path[-1],
+                    before=observed_obj,
+                    after=desired_obj,
+                    before_dict=observed_obj.model_dump(),
+                    after_dict=desired_obj.model_dump(),
+                    changed_attributes=self._attribute_changes(observed_obj, desired_obj),
+                ))
+
+        return Diff(
+            added=added,
+            removed=removed,
+            changed=changed,
+            total_desired=len(desired_paths),
+            total_observed=len(observed_paths),
+        )

{acex_devkit-1.2.0 → acex_devkit-1.3.0}/src/acex_devkit/configdiffer/diff.py

@@ -22,9 +22,11 @@ class ComponentDiffOp(str, Enum):
 
 class AttributeChange(BaseModel):
     """Represents a change to a single attribute within a component"""
+    model_config = {"arbitrary_types_allowed": True}
+
     attribute_name: str
-    before: Optional[AttributeValue[Any]] = None
-    after: Optional[AttributeValue[Any]] = None
+    before: Optional[Any] = None
+    after: Optional[Any] = None
 
 
 class ComponentChange(BaseModel):

{acex_devkit-1.2.0 → acex_devkit-1.3.0}/src/acex_devkit/models/composed_configuration.py

@@ -52,13 +52,22 @@ class SystemConfig(BaseModel):
 #class TripleA(BaseModel): ...
 
 # Trying to avoid using "Logging" or "logging" as names for anything due to conflicts with standard lib.
-class LoggingComponents(BaseModel): 
+class RemoteServers(BaseModel):
+    servers: Dict[str, RemoteServer] = {}
+
+class VtyLines(BaseModel):
+    lines: Dict[str, VtyLine] = {}
+
+class LogFiles(BaseModel):
+    files: Dict[str, FileLogging] = {}
+
+class LoggingComponents(BaseModel):
     config: LoggingConfig = LoggingConfig()
     console: Optional[Console] = None
-    remote_servers: Optional[Dict[str, RemoteServer]] = None
+    remote_servers: Optional[RemoteServers] = RemoteServers()
     events: Optional[LoggingEvents] = None
-    vty: Optional[Dict[str, VtyLine]] = None
-    files: Optional[Dict[str, FileLogging]] = None
+    vty: Optional[VtyLines] = VtyLines()
+    files: Optional[LogFiles] = LogFiles()
 
 class NtpConfig(BaseModel):
     enabled: AttributeValue[bool] = AttributeValue(value=False)
@@ -73,7 +82,7 @@ class NtpServer(BaseModel):
 
 class Ntp(BaseModel): 
     config: Optional[NtpConfig] = None
-    servers: Optional[Dict[str, NtpServer]] = None
+    servers: Optional[Dict[str, NtpServer]] = {}
 
 class SshServer(BaseModel): 
     enable: Optional[AttributeValue[bool]] = None
@@ -100,7 +109,7 @@ class AuthorizedKey(BaseModel):
 
 class Ssh(BaseModel): 
     config: Optional[SshServer] = None
-    host_keys: Optional[Dict[str, AuthorizedKey]] = None
+    host_keys: Optional[Dict[str, AuthorizedKey]] = {}
 
 class Lldp(BaseModel): ...
 
@@ -225,11 +234,11 @@ class StaticRouteNextHop(BaseModel):
 class StaticRoute(BaseModel):
     route_name: Optional[AttributeValue[str]] = None
     prefix: AttributeValue[str]
-    next_hops: Optional[Dict[str, StaticRouteNextHop]] = None
+    next_hops: Optional[Dict[str, StaticRouteNextHop]] = {}
     network_instance: Optional[AttributeValue[str]] = None
 
 class Protocols(BaseModel):
-    static_routes: Optional[Dict[str, StaticRoute]] = None
+    static_routes: Optional[Dict[str, StaticRoute]] = {}
     # OSPF, BGP, etc. can be added here as needed
 
 class RouteTarget(BaseModel):
@@ -245,9 +254,9 @@ class InterInstancePolicy(BaseModel):
 class NetworkInstance(BaseModel): 
     name: AttributeValue[str]
     description: Optional[AttributeValue[str]] = None
-    vlans: Optional[Dict[str, Vlan]] = None
+    vlans: Optional[Dict[str, Vlan]] = {}
     interfaces: Optional[Dict[str, Reference]] = {}
-    inter_instance_policies: Optional[Dict[str, InterInstancePolicy]] = None
+    inter_instance_policies: Optional[Dict[str, InterInstancePolicy]] = {}
     protocols: Optional[Protocols] = Protocols()
 
 class LacpConfig(BaseModel):
@@ -257,7 +266,7 @@ class LacpConfig(BaseModel):
 
 class Lacp(BaseModel):
     config: Optional[LacpConfig] = LacpConfig()
-    interfaces: Optional[Dict[str, Interface]] = None
+    interfaces: Optional[Dict[str, Interface]] = {}
 
 # SNMP
 class SnmpAccess(str, Enum):
@@ -455,12 +464,12 @@ class TrapEvent(BaseModel):
 #class SnmpTrap(BaseModel): ...
 
 class Snmp(BaseModel):
-    config: Optional[Dict[str, SnmpConfig]] = None
-    communities: Optional[Dict[str, SnmpCommunity]] = None
-    users: Optional[Dict[str, SnmpUser]] = None
-    trap_servers: Optional[Dict[str, SnmpServer]] = None
-    trap_events: Optional[Dict[str, TrapEvent]] = None
-    views: Optional[Dict[str, SnmpView]] = None
+    config: Optional[Dict[str, SnmpConfig]] = {}
+    communities: Optional[Dict[str, SnmpCommunity]] = {}
+    users: Optional[Dict[str, SnmpUser]] = {}
+    trap_servers: Optional[Dict[str, SnmpServer]] = {}
+    trap_events: Optional[Dict[str, TrapEvent]] = {}
+    views: Optional[Dict[str, SnmpView]] = {}
 
 # AAA
 class aaaBaseClass(BaseModel):
@@ -509,8 +518,8 @@ class aaaServerGroupAttributes(BaseModel):
     """
     enable: Optional[AttributeValue[bool]] = None
     type: Optional[AttributeValue[Literal['tacacs','radius']]] = None
-    tacacs: Optional[Dict[str, aaaTacacsAttributes]] = None
-    radius: Optional[Dict[str, aaaRadiusAttributes]] = None
+    tacacs: Optional[Dict[str, aaaTacacsAttributes]] = {}
+    radius: Optional[Dict[str, aaaRadiusAttributes]] = {}
 
 # Authentication Models
 class aaaAuthenticationMethods(aaaBaseClass):
@@ -540,19 +549,19 @@ class authenticationUser(aaaBaseClass):
     role: Optional[AttributeValue[str]] = None
 
 class aaaAuthenticationUsers(aaaBaseClass):
-    username: Optional[Dict[str, authenticationUser]] = None
+    username: Optional[Dict[str, authenticationUser]] = {}
 
 class adminUser(aaaBaseClass):
     admin_password: Optional[AttributeValue[str]] = None
     admin_password_hashed: Optional[AttributeValue[str]] = None
 
 class aaaAuthenticationAdminUsers(BaseModel):
-    config: Optional[Dict[str, adminUser]] = None
+    config: Optional[Dict[str, adminUser]] = {}
 
 class aaaAuthentication(BaseModel):
-    config: Optional[Dict[str, aaaAuthenticationMethods]] = None
-    admin_user: Optional[Dict[str, aaaAuthenticationAdminUsers]] = None
-    users: Optional[Dict[str, aaaAuthenticationUsers]] = None
+    config: Optional[Dict[str, aaaAuthenticationMethods]] = {}
+    admin_user: Optional[Dict[str, aaaAuthenticationAdminUsers]] = {}
+    users: Optional[Dict[str, aaaAuthenticationUsers]] = {}
 
 # Authorization Models
 class aaaAuthorizationMethods(aaaBaseClass):
@@ -582,8 +591,8 @@ class aaaAuthorizationEvents(aaaBaseClass):
     event: Optional[AttributeValue[str]] = None
 
 class aaaAuthorization(BaseModel):
-    config: Optional[Dict[str, aaaAuthorizationMethods]] = None
-    events: Optional[Dict[str, aaaAuthorizationEvents]] = None
+    config: Optional[Dict[str, aaaAuthorizationMethods]] = {}
+    events: Optional[Dict[str, aaaAuthorizationEvents]] = {}
 
 # Accounting Models
 class aaaAccountingMethods(BaseModel):
@@ -611,15 +620,15 @@ class aaaAccountingEvents(BaseModel):
     event: Optional[AttributeValue[str]] = None
 
 class aaaAccounting(BaseModel):
-    config: Optional[Dict[str, aaaAccountingMethods]] = None
-    events: Optional[Dict[str, aaaAccountingEvents]] = None
+    config: Optional[Dict[str, aaaAccountingMethods]] = {}
+    events: Optional[Dict[str, aaaAccountingEvents]] = {}
 
 class aaaGlobalAttributes(BaseModel):
     enabled: Optional[AttributeValue[bool]] = False # default False
 
 class TripleA(BaseModel):
     config: aaaGlobalAttributes = aaaGlobalAttributes()
-    server_groups: Optional[Dict[str, aaaServerGroupAttributes]] = None
+    server_groups: Optional[Dict[str, aaaServerGroupAttributes]] = {}
     authentication: aaaAuthentication = aaaAuthentication()
     authorization: aaaAuthorization = aaaAuthorization()
     accounting: aaaAccounting = aaaAccounting()
@@ -652,11 +661,14 @@ class ComposedConfiguration(BaseModel):
     stp: Optional[SpanningTree] = SpanningTree()
 
 
-""" 
+"""
 GUIDELINES FOR COMPOSED CONFIGURATION:
 
 1. All values must always be typed as AttributeValue.
 2. Containers must always be defined as hierarchical pydantic types, no dicts as placeholders.
-3. Component collections are always Dict[str, BaseModel] — the key identifies the component
-4. Default values for Optional is always None.
+3. Component collections must use a typed container class (e.g. RemoteServers, VtyLines) with an inner
+   Dict[str, BaseModel] field — the key identifies the component. Raw Dict fields are not allowed at
+   the container level.
+4. Default values for Optional containers are always an empty instance of the container class, e.g.
+   Optional[RemoteServers] = RemoteServers(). Never default to None or a raw empty dict for collections.
 """

{acex_devkit-1.2.0 → acex_devkit-1.3.0}/src/acex_devkit/models/logging.py

@@ -50,7 +50,7 @@ class RemoteServer(BaseModel):
     name: Optional[AttributeValue[str]] = None
     host: Optional[AttributeValue[str]] = None
     port: Optional[AttributeValue[int]] = None
-    transfer: Optional[AttributeValue[str]] = None
+    transport: Optional[AttributeValue[str]] = None
     source_address: Optional[AttributeValue[str]] = None # Can be an IP address or an interface reference
 
 class VtyLine(BaseModel):

acex_devkit-1.2.0/src/acex_devkit/configdiffer/configdiffer.py

@@ -1,178 +0,0 @@
-from pydantic import BaseModel
-from typing import Any, Dict, List, Iterator, Tuple
-
-from acex_devkit.models.composed_configuration import ComposedConfiguration, Reference, ReferenceTo, ReferenceFrom, Metadata
-from acex_devkit.models.attribute_value import AttributeValue
-from acex_devkit.configdiffer.diff import Diff, ComponentChange, AttributeChange, ComponentDiffOp
-
-import json
-
-
-class ConfigDiffer:
-
-    IGNORED_KEYS = ["metadata", "logging", "ssh", "snmp", "network_instances", "interfaces", "ntp", "domain_name", "location", "contact", "motd_banner"]
-
-    def _clean_metadata(self, obj: dict) -> dict:
-        """
-        Recursively ignored keys.
-        """
-        if not isinstance(obj, dict):
-            return obj
-        cleaned = {}
-        for k, v in obj.items():
-            if k in self.__class__.IGNORED_KEYS:
-                continue
-            if isinstance(v, dict):
-                cleaned[k] = self._clean_metadata(v)
-            elif isinstance(v, list):
-                cleaned[k] = [self._clean_metadata(item) if isinstance(item, dict) else item for item in v]
-            else:
-                cleaned[k] = v
-        return cleaned
-
-
-    def _dump_to_dicts(self, config: ComposedConfiguration) -> dict:
-        """
-        Dumps to dict, removes unnecessary keys except component_class. 
-        """
-        # Remove most metadata, but keep component_class for type identification
-        config_dict = config.model_dump(exclude_unset=True)
-        return self._clean_metadata(config_dict)
-
-
-    def _flatten(self, d: dict, path: tuple = ()) -> Dict[tuple, dict]:
-        """
-        Recursively walk the tree and collect every component (dict with
-        'component_class') into a flat mapping of path → component_dict.
-
-        Example result:
-            {
-                ('interfaces', 'GigabitEthernet0/0/1'): {...},
-                ('network_instances', 'default', 'vlans', '100'): {...},
-            }
-        """
-        result = {}
-        for key, value in d.items():
-            current_path = path + (key,)
-            if not isinstance(value, dict):
-                continue
-            # Try to find deeper components first
-            deeper = self._flatten(value, current_path)
-            if deeper:
-                # Sub-components found — use those (don't emit current level)
-                result.update(deeper)
-            elif any(isinstance(v, dict) and 'value' in v for v in value.values()):
-                # No sub-components, but this dict has AttributeValue fields → it's a leaf
-                result[current_path] = value
-        return result
-
-
-
-    def _get_by_path(self, config: ComposedConfiguration, path: tuple) -> Any:
-        """
-        Traverse the ComposedConfiguration object using a path tuple and return
-        the actual Pydantic model instance (or primitive) at that location.
-
-        Example:
-            path = ('interfaces', 'GigabitEthernet0/0/1')
-            → returns the actual SoftwareLoopbackInterface / EthernetCsmacdInterface etc.
-        """
-        obj = config
-        for key in path:
-            if isinstance(obj, dict):
-                obj = obj[key]
-            else:
-                obj = getattr(obj, key)
-        return obj
-
-    def _attribute_changes(self, before: dict, after: dict) -> List[AttributeChange]:
-        """
-        Compare two component dicts and return a list of changed attributes.
-        """
-        changes = []
-        for key in set(before.keys()) | set(after.keys()):
-            b = before.get(key)
-            a = after.get(key)
-            if b != a:
-                changes.append(AttributeChange(attribute_name=key, before=b, after=a))
-        return changes
-
-    def diff(self, *, desired_config: ComposedConfiguration, observed_config: ComposedConfiguration) -> Diff:
-        """
-        Compare two ComposedConfiguration objects and return a component-based diff.
-
-        Walks both configs using Pydantic model structure (not heuristics) to find
-        all named components inside Dict[str, Model] containers. Components are
-        identified by their full path, e.g. ('interfaces', 'GigabitEthernet0/0/1').
-
-        Args:
-            desired_config: The target configuration we want to achieve.
-            observed_config: The current configuration as observed on the device.
-
-        Returns:
-            Diff: A structured diff showing added, removed, and changed components.
-        """
-        flat_observed = self._flatten(self._dump_to_dicts(observed_config))
-        flat_desired = self._flatten(self._dump_to_dicts(desired_config))
-
-        observed_paths = set(flat_observed.keys())
-        desired_paths = set(flat_desired.keys())
-
-
-        added = []
-        removed = []
-        changed = []
-
-        for path in desired_paths - observed_paths:
-            obj = self._get_by_path(desired_config, path)
-            added.append(ComponentChange(
-                op=ComponentDiffOp.ADD,
-                path=list(path),
-                component_type=type(obj),
-                component_name=path[-1],
-                before=None,
-                after=obj,
-                before_dict=None,
-                after_dict=flat_desired[path],
-            ))
-
-        for path in observed_paths - desired_paths:
-            obj = self._get_by_path(observed_config, path)
-            removed.append(ComponentChange(
-                op=ComponentDiffOp.REMOVE,
-                path=list(path),
-                component_type=type(obj),
-                component_name=path[-1],
-                before=obj,
-                after=None,
-                before_dict=flat_observed[path],
-                after_dict=None,
-            ))
-
-        for path in desired_paths & observed_paths:
-            desired_comp = flat_desired[path]
-            observed_comp = flat_observed[path]
-            if desired_comp != observed_comp:
-                desired_obj = self._get_by_path(desired_config, path)
-                observed_obj = self._get_by_path(observed_config, path)
-                changed.append(ComponentChange(
-                    op=ComponentDiffOp.CHANGE,
-                    path=list(path),
-                    component_type=type(desired_obj),
-                    component_name=path[-1],
-                    before=observed_obj,
-                    after=desired_obj,
-                    before_dict=observed_comp,
-                    after_dict=desired_comp,
-                    changed_attributes=self._attribute_changes(observed_comp, desired_comp),
-                ))
-
-        return Diff(
-            added=added,
-            removed=removed,
-            changed=changed,
-            total_desired=len(desired_paths),
-            total_observed=len(observed_paths),
-        )
-
-