acex-devkit 1.2.1__tar.gz → 1.3.1__tar.gz

{acex_devkit-1.2.1 → acex_devkit-1.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: acex-devkit
-Version: 1.2.1
+Version: 1.3.1
 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.1 → acex_devkit-1.3.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "acex-devkit"
-version = "1.2.1"
+version = "1.3.1"
 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.1/src/acex_devkit/configdiffer/configdiffer.py

@@ -0,0 +1,211 @@
+from collections import defaultdict
+from pydantic import BaseModel
+from typing import Any, Dict, List, get_args
+
+from acex_devkit.models.composed_configuration import ComposedConfiguration
+from acex_devkit.models.attribute_value import AttributeValue
+from acex_devkit.models.container_entry import ContainerEntry
+from acex_devkit.configdiffer.diff import Diff, ComponentChange, AttributeChange, ComponentDiffOp
+
+
+class ConfigDiffer:
+
+    def _is_leaf(self, model: BaseModel) -> bool:
+        """A model is a leaf if it has at least one direct AttributeValue field."""
+        for field_info in model.model_fields.values():
+            ann = field_info.annotation
+            if isinstance(ann, type) and issubclass(ann, AttributeValue):
+                return True
+            for arg in get_args(ann):
+                if isinstance(arg, type) and issubclass(arg, AttributeValue):
+                    return True
+        return False
+
+    def _flatten(self, model: BaseModel, path: tuple = ()) -> Dict[tuple, BaseModel]:
+        """
+        Recursively walk a model tree, collecting leaf nodes.
+        A leaf is any BaseModel that has direct AttributeValue fields.
+        A model can be both a leaf (stored) and have children (recursed into).
+        Returns a flat mapping of path → leaf instance.
+        """
+        result = {}
+
+        # Store this model if it has AttributeValue fields (e.g. SystemConfig, NtpServer, NetworkInstance)
+        if self._is_leaf(model):
+            result[path] = model
+
+        # Walk each field declared on the model (e.g. System has config, aaa, logging, ntp, ssh, snmp)
+        for field_name in model.model_fields:
+            value = getattr(model, field_name, None)
+            if value is None:
+                continue
+
+            # Skip data fields — AttributeValue holds actual config values (e.g. hostname, enabled)
+            if isinstance(value, AttributeValue):
+                continue
+
+            # Single nested model — recurse deeper (e.g. System.config → SystemConfig, System.ssh → Ssh)
+            if isinstance(value, BaseModel):
+                result.update(self._flatten(value, path + (field_name,)))
+
+            # Keyed collection — recurse into each entry (e.g. interfaces: Dict[str, Interface])
+            elif isinstance(value, dict):
+                for key, item in value.items():
+                    # Each dict entry is a named component (e.g. "Gi0/0/1" → EthernetCsmacdInterface)
+                    if isinstance(item, BaseModel):
+                        result.update(self._flatten(item, path + (field_name, key)))
+
+        return result
+
+
+    def _attribute_changes(self, before: BaseModel, after: BaseModel) -> List[AttributeChange]:
+        """Compare two component 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 _identity_key(self, model: BaseModel) -> tuple:
+        """Extract identity values from a ContainerEntry for matching.
+        Returns a tuple of raw values (unwrapped from AttributeValue) from identity_fields."""
+        fields = getattr(model, "identity_fields", ())
+        values = []
+        for f in fields:
+            v = getattr(model, f, None)
+            # Unwrap AttributeValue to its raw value for hashing
+            if isinstance(v, AttributeValue):
+                v = v.value
+            values.append(v)
+        return tuple(values)
+
+    def _make_change(self, op: ComponentDiffOp, path: tuple, before=None, after=None) -> ComponentChange:
+        """Build a ComponentChange from an operation, path, and before/after models."""
+        obj = after or before
+        return ComponentChange(
+            op=op,
+            path=list(path),
+            component_type=type(obj),
+            component_name=path[-1] if path else "",
+            before=before,
+            after=after,
+            before_dict=before.model_dump() if before else None,
+            after_dict=after.model_dump() if after else None,
+            changed_attributes=self._attribute_changes(before, after) if (before and after) else [],
+        )
+
+    def _diff_singletons(self, desired: Dict[tuple, BaseModel], observed: Dict[tuple, BaseModel]) -> List[ComponentChange]:
+        """Diff leaves that are not ContainerEntry — matched by exact path."""
+        changes = []
+        all_paths = set(desired) | set(observed)
+        for path in all_paths:
+            d = desired.get(path)
+            o = observed.get(path)
+            if d and o:
+                if d != o:
+                    changes.append(self._make_change(ComponentDiffOp.CHANGE, path, before=o, after=d))
+            elif d:
+                changes.append(self._make_change(ComponentDiffOp.ADD, path, after=d))
+            else:
+                changes.append(self._make_change(ComponentDiffOp.REMOVE, path, before=o))
+        return changes
+
+    def _diff_entries(self, desired: Dict[tuple, BaseModel], observed: Dict[tuple, BaseModel]) -> List[ComponentChange]:
+        """Diff ContainerEntry leaves — matched by identity_fields within each container scope."""
+        changes = []
+
+        # Group by container path (parent = path[:-1]) so identity matching is scoped
+        desired_by_container: Dict[tuple, Dict[str, BaseModel]] = defaultdict(dict)
+        observed_by_container: Dict[tuple, Dict[str, BaseModel]] = defaultdict(dict)
+
+        for path, model in desired.items():
+            desired_by_container[path[:-1]][path[-1]] = model
+        for path, model in observed.items():
+            observed_by_container[path[:-1]][path[-1]] = model
+
+        all_containers = set(desired_by_container) | set(observed_by_container)
+
+        for container_path in all_containers:
+            d_components = desired_by_container.get(container_path, {})
+            o_components = observed_by_container.get(container_path, {})
+
+            # Build identity → (key, model) lookup for observed
+            o_by_identity: Dict[tuple, tuple[str, BaseModel]] = {}
+            o_by_key: Dict[str, BaseModel] = dict(o_components)
+            for key, model in o_components.items():
+                identity = self._identity_key(model)
+                if identity:  # non-empty identity_fields — match by field values
+                    o_by_identity[identity] = (key, model)
+
+            matched_o_keys = set()
+
+            for d_key, d_model in d_components.items():
+                d_identity = self._identity_key(d_model)
+                o_key, o_model = None, None
+
+                if d_identity:
+                    # Match by identity field values (e.g. same address, same vlan_id)
+                    match = o_by_identity.get(d_identity)
+                    if match:
+                        o_key, o_model = match
+                else:
+                    # identity_fields = () — fall back to dict key matching
+                    if d_key in o_by_key:
+                        o_key, o_model = d_key, o_by_key[d_key]
+
+                if o_model:
+                    matched_o_keys.add(o_key)
+                    if d_model != o_model:
+                        changes.append(self._make_change(
+                            ComponentDiffOp.CHANGE, container_path + (d_key,),
+                            before=o_model, after=d_model,
+                        ))
+                else:
+                    changes.append(self._make_change(
+                        ComponentDiffOp.ADD, container_path + (d_key,),
+                        after=d_model,
+                    ))
+
+            # Remaining observed entries that weren't matched → removed
+            for o_key, o_model in o_components.items():
+                if o_key not in matched_o_keys:
+                    changes.append(self._make_change(
+                        ComponentDiffOp.REMOVE, container_path + (o_key,),
+                        before=o_model,
+                    ))
+
+        return changes
+
+    def diff(self, *, desired_config: ComposedConfiguration, observed_config: ComposedConfiguration) -> Diff:
+        """
+        Compare two ComposedConfiguration objects and return a component-based diff.
+
+        Singletons (fixed-path leaves like SystemConfig) are matched by path.
+        ContainerEntry leaves (dict entries like interfaces) are matched by identity_fields,
+        handling cases where keys differ (e.g. "Gi0/0/1" vs "GigabitEthernet0/0/1").
+        """
+        flat_desired = self._flatten(desired_config)
+        flat_observed = self._flatten(observed_config)
+
+        # Split into singletons (path-matched) and entries (identity-matched)
+        singleton_d = {p: m for p, m in flat_desired.items() if not isinstance(m, ContainerEntry)}
+        singleton_o = {p: m for p, m in flat_observed.items() if not isinstance(m, ContainerEntry)}
+        entry_d = {p: m for p, m in flat_desired.items() if isinstance(m, ContainerEntry)}
+        entry_o = {p: m for p, m in flat_observed.items() if isinstance(m, ContainerEntry)}
+
+        all_changes = self._diff_singletons(singleton_d, singleton_o) + self._diff_entries(entry_d, entry_o)
+
+        added = [c for c in all_changes if c.op == ComponentDiffOp.ADD]
+        removed = [c for c in all_changes if c.op == ComponentDiffOp.REMOVE]
+        changed = [c for c in all_changes if c.op == ComponentDiffOp.CHANGE]
+
+        return Diff(
+            added=added,
+            removed=removed,
+            changed=changed,
+            total_desired=len(flat_desired),
+            total_observed=len(flat_observed),
+        )

{acex_devkit-1.2.1 → acex_devkit-1.3.1}/src/acex_devkit/models/acl_model.py

@@ -1,8 +1,9 @@
 from pydantic import BaseModel
 from ipaddress import IPv4Network, IPv6Network
 from acex_devkit.models.attribute_value import AttributeValue
+from acex_devkit.models.container_entry import ContainerEntry
 from enum import Enum
-from typing import Optional, Dict, Literal
+from typing import ClassVar, Optional, Dict, Literal
 
 class AclProtoclOptions(str, Enum):
     TCP = 'tcp'
@@ -12,7 +13,8 @@ class AclProtoclOptions(str, Enum):
     IP = 'ip'
     ANY = 'any'
 
-class IpAclOptions(BaseModel):
+class IpAclOptions(ContainerEntry, BaseModel):
+    identity_fields: ClassVar[tuple[str, ...]] = ("sequence_id",)
     description: Optional[AttributeValue[str]] = None
     source_port: Optional[AttributeValue[str]] = None # e.g., "100-200"
     destination_port: Optional[AttributeValue[str]] = None # e.g., "300-400"
@@ -64,12 +66,14 @@ class Ipv6AclEntryAttributes(IpAclOptions):
     destination_address: Optional[AttributeValue[IPv6Network | Literal['any']]] = None # Destination IPv6 address prefix.
     ipv6_acl: Optional[AttributeValue[str]] = None # Reference to the ACL Set this entry belongs to.
 
-class Ipv4AclAttributes(BaseModel):
+class Ipv4AclAttributes(ContainerEntry, BaseModel):
+    identity_fields: ClassVar[tuple[str, ...]] = ("name",)
     name: AttributeValue[str]
     type: AttributeValue[str] = "ipv4_acl"
     acl_entries: Optional[Dict[str, Ipv4AclEntryAttributes]] = None
 
-class Ipv6AclAttributes(BaseModel):
+class Ipv6AclAttributes(ContainerEntry, BaseModel):
+    identity_fields: ClassVar[tuple[str, ...]] = ("name",)
     name: AttributeValue[str]
     type: AttributeValue[str] = "ipv6_acl"
     acl_entries: Optional[Dict[str, Ipv6AclEntryAttributes]] = None

{acex_devkit-1.2.1 → acex_devkit-1.3.1}/src/acex_devkit/models/attribute_value.py

@@ -113,6 +113,14 @@ class AttributeValue(BaseModel, Generic[T]):
             return str(value)
         return value
 
+    def __eq__(self, other):
+        if not isinstance(other, AttributeValue):
+            return NotImplemented
+        return self.value == other.value
+
+    def __hash__(self):
+        return hash(self.value)
+
     # Convenience helpers
     def is_external(self) -> bool:
         return isinstance(self.value, ExternalValue)

{acex_devkit-1.2.1 → acex_devkit-1.3.1}/src/acex_devkit/models/composed_configuration.py

@@ -5,10 +5,11 @@ from enum import Enum
 
 from acex_devkit.models.external_value import ExternalValue
 from acex_devkit.models.attribute_value import AttributeValue
+from acex_devkit.models.container_entry import ContainerEntry
 from acex_devkit.models.logging import (
     LoggingConfig,
     Console,
-    RemoteServer,
+    RemoteServers,
     VtyLine,
     FileLogging,
     LoggingEvents
@@ -25,7 +26,8 @@ class Metadata(BaseModel):
     type: Optional[str] = "str"
     value_source: MetadataValueType = MetadataValueType.CONCRETE 
 
-class Reference(BaseModel): 
+class Reference(ContainerEntry, BaseModel):
+    identity_fields: ClassVar[tuple[str, ...]] = ("pointer",)
     pointer: str
     metadata: Metadata = Metadata(type="str", value_source="reference")
 
@@ -50,20 +52,27 @@ class SystemConfig(BaseModel):
     motd_banner: Optional[AttributeValue[str]] = None
 
 #class TripleA(BaseModel): ...
-
 # Trying to avoid using "Logging" or "logging" as names for anything due to conflicts with standard lib.
-class LoggingComponents(BaseModel): 
+
+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)
 
-class NtpServer(BaseModel):
+class NtpServer(ContainerEntry, BaseModel):
+    identity_fields: ClassVar[tuple[str, ...]] = ("address",)
     address: AttributeValue[str]
     port: Optional[AttributeValue[int]] = None
     version: Optional[AttributeValue[int]] = None
@@ -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
@@ -94,25 +103,27 @@ class AuthorizedKeyAlgorithms(str, Enum):
     SSH_RSA = "ssh-rsa"
     SSH_DSS = "ssh-dss"
 
-class AuthorizedKey(BaseModel):
-    algorithm: AuthorizedKeyAlgorithms
-    public_key: str
+class AuthorizedKey(ContainerEntry, BaseModel):
+    identity_fields: ClassVar[tuple[str, ...]] = ("public_key",)
+    algorithm: Optional[AttributeValue[AuthorizedKeyAlgorithms]] = None
+    public_key: Optional[AttributeValue[str]] = None
 
-class Ssh(BaseModel): 
+class Ssh(BaseModel):
     config: Optional[SshServer] = None
-    host_keys: Optional[Dict[str, AuthorizedKey]] = None
+    host_keys: Optional[Dict[str, AuthorizedKey]] = {}
 
 class Lldp(BaseModel): ...
 
-class Vlan(BaseModel):
+class Vlan(ContainerEntry, BaseModel):
+    identity_fields: ClassVar[tuple[str, ...]] = ("vlan_id",)
     name: AttributeValue[str]
     vlan_id: Optional[AttributeValue[int]] = None
     vlan_name: Optional[AttributeValue[str]] = None
     network_instance: Optional[AttributeValue[str]] = None
-    metadata: Optional[Metadata] = Metadata()
 
-class Interface(BaseModel): 
+class Interface(ContainerEntry, BaseModel):
     "Base class for all interfaces"
+    identity_fields: ClassVar[tuple[str, ...]] = ("index", "type")
     index: AttributeValue[int]
     name: AttributeValue[str]
 
@@ -120,7 +131,6 @@ class Interface(BaseModel):
     enabled: Optional[AttributeValue[bool]] = None
     ipv4: Optional[AttributeValue[str]] = None
     
-    metadata: Optional[Metadata] = Metadata()
     type: Literal[
         "ethernetCsmacd",
         "ieee8023adLag",
@@ -190,21 +200,21 @@ class Ieee8023adLagInterface(Interface):
 class L3IpvlanInterface(Interface):
     "SVI Interface"
     type: Literal["l3ipvlan"] = "l3ipvlan"
-    vlan_id: Optional[int] = None
+    vlan_id: Optional[AttributeValue[int]] = None
 
 class SoftwareLoopbackInterface(Interface):
     "Loopback Interface"
     type: Literal["softwareLoopback"] = "softwareLoopback"
 
     # Loopback har varken vlan, duplex eller speed
-    vlan_id: Optional[int] = None
+    vlan_id: Optional[AttributeValue[int]] = None
     ipv4: Optional[AttributeValue[str]] = None
 
 class SubInterface(Interface):
     "Subinterface"
     type: Literal["subinterface"] = "subinterface"
 
-    vlan_id: Optional[int] = None
+    vlan_id: Optional[AttributeValue[int]] = None
     ipv4: Optional[AttributeValue[str]] = None
 
 class ManagementInterface(Interface):
@@ -212,9 +222,10 @@ class ManagementInterface(Interface):
     type: Literal["managementInterface"] = "managementInterface"
 
     # Mgmt har inte vlan
-    vlan_id: Optional[int] = None
+    vlan_id: Optional[AttributeValue[int]] = None
 
-class StaticRouteNextHop(BaseModel):
+class StaticRouteNextHop(ContainerEntry, BaseModel):
+    identity_fields: ClassVar[tuple[str, ...]] = ("next_hop",)
     index: Optional[AttributeValue[int]] = None
     next_hop: AttributeValue[str] # can be an IP address or an interface. Reference will be handled in config component
     metric: Optional[AttributeValue[int]] = None
@@ -222,14 +233,15 @@ class StaticRouteNextHop(BaseModel):
     network_instance: Optional[AttributeValue[str]] = None
 
 
-class StaticRoute(BaseModel):
+class StaticRoute(ContainerEntry, BaseModel):
+    identity_fields: ClassVar[tuple[str, ...]] = ("prefix",)
     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):
@@ -239,15 +251,17 @@ class ImportExportPolicy(BaseModel):
     export_route_target: Optional[List[RouteTarget]] = None
     import_route_target: Optional[List[RouteTarget]] = None
 
-class InterInstancePolicy(BaseModel):
+class InterInstancePolicy(ContainerEntry, BaseModel):
+    identity_fields: ClassVar[tuple[str, ...]] = ()
     import_export_policy: ImportExportPolicy
 
-class NetworkInstance(BaseModel): 
+class NetworkInstance(ContainerEntry, BaseModel):
+    identity_fields: ClassVar[tuple[str, ...]] = ("name",)
     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 +271,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):
@@ -288,14 +302,16 @@ class SnmpPrivProtocol(str, Enum):
 	AES256 = "AES256"
 
 
-class SnmpConfig(BaseModel):
-	enabled: AttributeValue[bool] = AttributeValue(value=False)
-	engine_id: Optional[AttributeValue[str]] = None
-	location: Optional[AttributeValue[str]] = None
-	contact: Optional[AttributeValue[str]] = None
+class SnmpConfig(ContainerEntry, BaseModel):
+    identity_fields: ClassVar[tuple[str, ...]] = ()
+    enabled: AttributeValue[bool] = AttributeValue(value=False)
+    engine_id: Optional[AttributeValue[str]] = None
+    location: Optional[AttributeValue[str]] = None
+    contact: Optional[AttributeValue[str]] = None
 
 
-class SnmpCommunity(BaseModel):
+class SnmpCommunity(ContainerEntry, BaseModel):
+    identity_fields: ClassVar[tuple[str, ...]] = ("name",)
     name: AttributeValue[str]
     community: Optional[AttributeValue[str]] = None # Community string
     access: Optional[AttributeValue[SnmpAccess]] = AttributeValue(value=SnmpAccess.READ_ONLY)
@@ -306,22 +322,25 @@ class SnmpCommunity(BaseModel):
     clients: Optional[AttributeValue[List[str]]] = None # Juniper specific
 
 
-class SnmpUser(BaseModel):
-	username: AttributeValue[str]
-	security_level: Optional[AttributeValue[SnmpSecurityLevel]] = AttributeValue(value=SnmpSecurityLevel.NO_AUTH_NO_PRIV)
-	auth_protocol: Optional[AttributeValue[SnmpAuthProtocol]] = None
-	auth_password: Optional[AttributeValue[str]] = None
-	priv_protocol: Optional[AttributeValue[SnmpPrivProtocol]] = None
-	priv_password: Optional[AttributeValue[str]] = None
+class SnmpUser(ContainerEntry, BaseModel):
+    identity_fields: ClassVar[tuple[str, ...]] = ("username",)
+    username: AttributeValue[str]
+    security_level: Optional[AttributeValue[SnmpSecurityLevel]] = AttributeValue(value=SnmpSecurityLevel.NO_AUTH_NO_PRIV)
+    auth_protocol: Optional[AttributeValue[SnmpAuthProtocol]] = None
+    auth_password: Optional[AttributeValue[str]] = None
+    priv_protocol: Optional[AttributeValue[SnmpPrivProtocol]] = None
+    priv_password: Optional[AttributeValue[str]] = None
 
 
-class SnmpView(BaseModel):
-	name: AttributeValue[str]
-	oid: AttributeValue[str]
-	included: Optional[AttributeValue[bool]] = AttributeValue(value=True)
+class SnmpView(ContainerEntry, BaseModel):
+    identity_fields: ClassVar[tuple[str, ...]] = ("name",)
+    name: AttributeValue[str]
+    oid: AttributeValue[str]
+    included: Optional[AttributeValue[bool]] = AttributeValue(value=True)
 
 
-class SnmpServer(BaseModel):
+class SnmpServer(ContainerEntry, BaseModel):
+    identity_fields: ClassVar[tuple[str, ...]] = ("address",)
     name: Optional[AttributeValue[str]] = None
     address: AttributeValue[str]
     port: Optional[AttributeValue[int]] = AttributeValue(value=162)
@@ -448,25 +467,28 @@ class TrapEventOptions(str, Enum):
 	BULKSTAT_COLLECTION = "bulkstat_collection"
 	BULKSTAT_TRANSFER = "bulkstat_transfer"
 
-class TrapEvent(BaseModel):
+class TrapEvent(ContainerEntry, BaseModel):
+    identity_fields: ClassVar[tuple[str, ...]] = ("event_name",)
     name: Optional[AttributeValue[str]] = None
     event_name: Optional[AttributeValue[TrapEventOptions]] = None
 
 #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):
+class aaaBaseClass(ContainerEntry, BaseModel):
+    identity_fields: ClassVar[tuple[str, ...]] = ()  # key is identity (e.g. "default", "console")
     name: Optional[AttributeValue[str]] = None
 
-class aaaTacacsAttributes(BaseModel):
+class aaaTacacsAttributes(ContainerEntry, BaseModel):
+    identity_fields: ClassVar[tuple[str, ...]] = ("address",)
     port: Optional[AttributeValue[int]] = None
     secret_key: Optional[AttributeValue[str]] = None
     secret_key_hashed: Optional[AttributeValue[str]] = None
@@ -475,7 +497,8 @@ class aaaTacacsAttributes(BaseModel):
     source_interface: Optional[Reference] = None
     server_group: Optional[AttributeValue[str]] = None
 
-class aaaRadiusAttributes(BaseModel):
+class aaaRadiusAttributes(ContainerEntry, BaseModel):
+    identity_fields: ClassVar[tuple[str, ...]] = ("address",)
     auth_port: Optional[AttributeValue[int]] = None
     acct_port: Optional[AttributeValue[int]] = None
     secret_key: Optional[AttributeValue[str]] = None
@@ -486,7 +509,8 @@ class aaaRadiusAttributes(BaseModel):
     retransmit_attempts: Optional[AttributeValue[int]] = None
     server_group: Optional[AttributeValue[str]] = None
 
-class aaaServerGroupAttributes(BaseModel):
+class aaaServerGroupAttributes(ContainerEntry, BaseModel):
+    identity_fields: ClassVar[tuple[str, ...]] = ()  # key is the group name
     """
     Define a AAA server group that can contain multiple TACACS+ and/or RADIUS servers.
 
@@ -509,8 +533,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):
@@ -533,6 +557,7 @@ class aaaAuthenticationMethods(aaaBaseClass):
     # aaa authentication enable default group TACACS-GROUP-NEW enable
 
 class authenticationUser(aaaBaseClass):
+    identity_fields: ClassVar[tuple[str, ...]] = ("username",)
     username: Optional[AttributeValue[str]] = None
     password: Optional[AttributeValue[str]] = None
     password_hahsed: Optional[AttributeValue[str]] = None
@@ -540,19 +565,20 @@ 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
+class aaaAuthenticationAdminUsers(ContainerEntry, BaseModel):
+    identity_fields: ClassVar[tuple[str, ...]] = ()
+    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,13 +608,14 @@ 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):
+class aaaAccountingMethods(ContainerEntry, BaseModel):
+    identity_fields: ClassVar[tuple[str, ...]] = ()
     """
-    Define the accounting methods used by AAA. If you define a server group using the "aaaServerGroup" model, 
+    Define the accounting methods used by AAA. If you define a server group using the "aaaServerGroup" model,
     you can reference it here by its name, but only as a string.
 
     Example in config map:
@@ -600,10 +627,11 @@ class aaaAccountingMethods(BaseModel):
     #method: Optional[List[str]] = None # Ex. ['TACACS_GROUP','LOCAL']
     method: Optional[AttributeValue[str]] = None
 
-class aaaAccountingEvents(BaseModel):
+class aaaAccountingEvents(ContainerEntry, BaseModel):
+    identity_fields: ClassVar[tuple[str, ...]] = ()
     """
     Define accounting events.
-    
+
     Cisco example:
     aaa accounting send stop-record authentication failure
     """
@@ -611,15 +639,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 +680,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.3.1/src/acex_devkit/models/container_entry.py

@@ -0,0 +1,42 @@
+from typing import ClassVar
+
+
+class ContainerEntry:
+    """
+    Mixin for Pydantic models that are used as values in Dict[str, X] container fields.
+
+    Every subclass MUST declare `identity_fields` as a ClassVar[tuple[str, ...]]:
+      - Non-empty tuple: fields whose values uniquely identify this object.
+        The differ will match objects across desired/observed by these field values,
+        ignoring the dict key entirely.
+      - Empty tuple `()`: the dict key itself is the identity (key-based matching).
+        Use this for singleton-like entries (e.g., "global", "default") where no
+        field inside the object acts as a natural identifier.
+
+    Example:
+        class NtpServer(ContainerEntry, BaseModel):
+            identity_fields: ClassVar[tuple[str, ...]] = ("address",)
+            address: AttributeValue[str]
+            ...
+
+        class SpanningTreeGlobalConfig(ContainerEntry, BaseModel):
+            identity_fields: ClassVar[tuple[str, ...]] = ()  # key is identity
+            mode: Optional[AttributeValue[str]] = None
+            ...
+    """
+
+    identity_fields: ClassVar[tuple[str, ...]]
+
+    def __init_subclass__(cls, **kwargs):
+        super().__init_subclass__(**kwargs)
+        has_identity_fields = any(
+            "identity_fields" in c.__dict__
+            for c in cls.__mro__
+            if c is not ContainerEntry
+        )
+        if not has_identity_fields:
+            raise TypeError(
+                f"{cls.__name__} must declare 'identity_fields' as a ClassVar. "
+                f"Use identity_fields = ('field_name',) to match by field value, "
+                f"or identity_fields = () to match by dict key."
+            )

{acex_devkit-1.2.1 → acex_devkit-1.3.1}/src/acex_devkit/models/logging.py

@@ -1,7 +1,8 @@
 from pydantic import BaseModel
 from acex_devkit.models.attribute_value import AttributeValue
+from acex_devkit.models.container_entry import ContainerEntry
 from enum import Enum
-from typing import Optional, Dict
+from typing import ClassVar, Optional, Dict
 
 
 class LoggingServerBase(BaseModel): ...
@@ -46,20 +47,26 @@ class Console(BaseModel):
     line_number: Optional[AttributeValue[int]] = None
     logging_synchronous: Optional[AttributeValue[bool]] = None
 
-class RemoteServer(BaseModel):
+class RemoteServer(ContainerEntry, BaseModel):
+    identity_fields: ClassVar[tuple[str, ...]] = ("host",)
     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):
+class RemoteServers(BaseModel):
+    servers: Dict[str, RemoteServer] = {}
+
+class VtyLine(ContainerEntry, BaseModel):
+    identity_fields: ClassVar[tuple[str, ...]] = ("line_number",)
     name: Optional[AttributeValue[str]] = None
     line_number: Optional[AttributeValue[int]] = None
     logging_synchronous: Optional[AttributeValue[bool]] = None
     transport_input: Optional[AttributeValue[str]] = None # default is SSH. Mostly used by Cisco.
 
-class FileLogging(BaseModel):
+class FileLogging(ContainerEntry, BaseModel):
+    identity_fields: ClassVar[tuple[str, ...]] = ("filename",)
     name: Optional[AttributeValue[str]] = None # object name
     filename: Optional[AttributeValue[str]] = None # name of the file
     rotate: Optional[AttributeValue[int]] = None # How many versions to keep. Juniper specific.

{acex_devkit-1.2.1 → acex_devkit-1.3.1}/src/acex_devkit/models/spanning_tree.py

@@ -1,9 +1,11 @@
 from pydantic import BaseModel
 from acex_devkit.models.attribute_value import AttributeValue
+from acex_devkit.models.container_entry import ContainerEntry
 from enum import Enum
-from typing import Optional, Dict
+from typing import ClassVar, Optional, Dict
 
-class SpanningTreeGlobalAttributes(BaseModel):
+class SpanningTreeGlobalAttributes(ContainerEntry, BaseModel):
+    identity_fields: ClassVar[tuple[str, ...]] = ()
     mode: Optional[AttributeValue[str]] = None # Needs to be defined by user. Default for Cisco is RAPID-PVST and for Juniper it's just RSTP
     bpdu_filter: Optional[AttributeValue[bool]] = None # Disabled by default
     bpdu_guard: Optional[AttributeValue[bool]] = None # Disabled by default
@@ -20,19 +22,22 @@ class SpanningTreeModeConfig(BaseModel):
     hold_count: Optional[AttributeValue[int]] = None # Range 1..10
 
 ## RSTP
-class RstpAttributes(SpanningTreeModeConfig): ...
+class RstpAttributes(ContainerEntry, SpanningTreeModeConfig):
+    identity_fields: ClassVar[tuple[str, ...]] = ()
 
 class RSTPConfig(BaseModel):
     #config: RstpAttributes = RstpAttributes()
     config: Optional[Dict[str, RstpAttributes]] = None
 
 ### MSTP
-class MstpInstanceAttributes(SpanningTreeModeConfig):
+class MstpInstanceAttributes(ContainerEntry, SpanningTreeModeConfig):
+    identity_fields: ClassVar[tuple[str, ...]] = ("instance_id",)
     instance_id: AttributeValue[int] # range: 1..4094
     name: Optional[AttributeValue[str]] = None
     vlan: Optional[AttributeValue[list[int]]] = None # List of VLANs mapped to the MST instance
 
-class MstpAttributes(SpanningTreeModeConfig):
+class MstpAttributes(ContainerEntry, SpanningTreeModeConfig):
+    identity_fields: ClassVar[tuple[str, ...]] = ()
     revision: Optional[AttributeValue[int]] = None
     max_hop: Optional[AttributeValue[int]] = None # Range 1..255
 
@@ -42,7 +47,8 @@ class MSTPConfig(BaseModel):
     mst_instances: Optional[Dict[str, MstpInstanceAttributes]] = None
 
 ### Rapid PVST
-class RapidPVSTAttributes(SpanningTreeModeConfig):
+class RapidPVSTAttributes(ContainerEntry, SpanningTreeModeConfig):
+    identity_fields: ClassVar[tuple[str, ...]] = ("vlan",)
     """
     Docstring for RapidPVSTAttributes
     vlan can be a string or list. Depending on how NED is built it will check wether it's a single VLAN or multiple VLANs and then format the data to the correct format

acex_devkit-1.2.1/src/acex_devkit/configdiffer/configdiffer.py

@@ -1,158 +0,0 @@
-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),
-        )