acex-devkit 1.6.2__tar.gz → 1.7.1__tar.gz

{acex_devkit-1.6.2 → acex_devkit-1.7.1}/PKG-INFO

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

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "acex-devkit"
-version = "1.6.2"
+version = "1.7.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.6.2 → acex_devkit-1.7.1}/src/acex_devkit/__init__.py

@@ -8,10 +8,12 @@ from acex_devkit.drivers import (
     RendererBase,
     ParserBase,
 )
+from acex_devkit.normalizer import BaseNormalizer
 
 __all__ = [
     "NetworkElementDriver",
     "TransportBase",
     "RendererBase",
     "ParserBase",
+    "BaseNormalizer",
 ]

{acex_devkit-1.6.2 → acex_devkit-1.7.1}/src/acex_devkit/drivers/base.py

@@ -3,6 +3,9 @@
 from abc import ABC, abstractmethod
 from typing import Any, Dict
 
+from acex_devkit.models.node_response import NodeListItem
+from acex_devkit.models.management_connection import ManagementConnection
+
 
 class ParserBase(ABC):
     """Base class for configuration parsers."""
@@ -38,52 +41,51 @@ class RendererBase(ABC):
 
 
 class TransportBase(ABC):
-    """Base class for device transport/communication."""
-    
-    @abstractmethod
-    def connect(self) -> None:
-        """Establish connection to the device."""
-        pass
+    """Base class for device transport/communication.
 
-    @abstractmethod
-    def send(self, payload: Any) -> None:
-        """Send configuration to the device.
-        
-        Args:
-            payload: Configuration payload to send
-        """
-        pass
+    Each method is self-contained — the driver decides internally
+    whether to open/close sessions per call, pool connections, or
+    make stateless requests.
+
+    Args:
+        node: The node instance (identity, hostname, vendor, os, ned_id)
+        connection: Management connection (target_ip, connection_type)
+        **kwargs: Future use (credentials, options, etc.)
+    """
 
     @abstractmethod
-    def verify(self) -> bool:
-        """Verify configuration was applied correctly.
-        
-        Returns:
-            True if verification succeeded, False otherwise
-        """
+    def get_config(self, node: NodeListItem, connection: ManagementConnection, **kwargs) -> str:
+        """Fetch the full running configuration from a device."""
         pass
 
     @abstractmethod
-    def rollback(self) -> None:
-        """Rollback configuration if verification fails."""
+    def send_config(self, node: NodeListItem, connection: ManagementConnection, commands: list[str], **kwargs) -> str:
+        """Apply configuration commands to a device."""
         pass
 
+    def execute(self, node: NodeListItem, connection: ManagementConnection, commands: list[str], **kwargs) -> list[str]:
+        """Run arbitrary commands and return output per command. Opt-in per driver."""
+        raise NotImplementedError(f"{self.__class__.__name__} does not implement execute()")
+
 
 class NetworkElementDriver:
     """Base class for network element drivers.
-    
+
     Combines renderer, transport, and parser to provide complete
     configuration management for network devices.
-    
+
     Attributes:
         renderer_class: Renderer class to use (must be set in subclass)
         transport_class: Transport class to use (must be set in subclass)
         parser_class: Parser class to use (must be set in subclass)
+        normalizer_class: Optional normalizer class for stripping
+            non-intent config and masking secrets
     """
-    
+
     renderer_class = None
     transport_class = None
     parser_class = None
+    normalizer_class = None
 
     def __init__(self):
         """Initialize driver with renderer, transport, and parser instances."""
@@ -94,6 +96,7 @@ class NetworkElementDriver:
         self.renderer = self.renderer_class()
         self.transport = self.transport_class()
         self.parser = self.parser_class()
+        self.normalizer = self.normalizer_class() if self.normalizer_class else None
 
     @abstractmethod
     def render(self, logical_node: "LogicalNode", asset: Any = None) -> Any:
@@ -111,11 +114,31 @@ class NetworkElementDriver:
     @abstractmethod
     def parse(self, configuration: str) -> Any:
         """Parse device configuration.
-        
+
         Args:
             configuration: Raw device configuration
-            
+
         Returns:
             Parsed configuration model
         """
         return self.parser.parse(configuration)
+
+    def normalize(self, raw: str) -> str:
+        """Strip non-intent data (timestamps, auto-generated certs, etc.).
+
+        Returns the cleaned config string. If no normalizer is configured
+        the input is returned unchanged.
+        """
+        if self.normalizer is None:
+            return raw
+        return self.normalizer.normalize(raw).config
+
+    def mask(self, raw: str) -> str:
+        """Replace secrets with <REDACTED>.
+
+        Returns the masked config string. If no normalizer is configured
+        the input is returned unchanged.
+        """
+        if self.normalizer is None:
+            return raw
+        return self.normalizer.mask(raw).config

{acex_devkit-1.6.2 → acex_devkit-1.7.1}/src/acex_devkit/drivers/base_driver.py

@@ -1,6 +1,9 @@
 from abc import ABC, abstractmethod
 from typing import Any, Dict
 
+from acex_devkit.models.node_response import NodeListItem
+from acex_devkit.models.management_connection import ManagementConnection
+
 class ParserBase(ABC):
     @abstractmethod
     def parse(self, model: Dict[str, Any]) -> Any:
@@ -14,16 +17,18 @@ class RendererBase(ABC):
 
 class TransportBase(ABC):
     @abstractmethod
-    def connect(self) -> None: ...
-
-    @abstractmethod
-    def send(self, payload: Any) -> None: ...
+    def get_config(self, node: NodeListItem, connection: ManagementConnection, **kwargs) -> str:
+        """Fetch the full running configuration from a device."""
+        pass
 
     @abstractmethod
-    def verify(self) -> bool: ...
+    def send_config(self, node: NodeListItem, connection: ManagementConnection, commands: list[str], **kwargs) -> str:
+        """Apply configuration commands to a device."""
+        pass
 
-    @abstractmethod
-    def rollback(self) -> None: ...
+    def execute(self, node: NodeListItem, connection: ManagementConnection, commands: list[str], **kwargs) -> list[str]:
+        """Run arbitrary commands. Opt-in per driver."""
+        raise NotImplementedError(f"{self.__class__.__name__} does not implement execute()")
 
 class NetworkElementDriver:
     """Kombinerar renderer + transport – exponeras som en plugin."""

{acex_devkit-1.6.2 → acex_devkit-1.7.1}/src/acex_devkit/models/__init__.py

@@ -6,6 +6,7 @@
 from .external_value import ExternalValue
 from .attribute_value import AttributeValue
 from .node_response import NodeResponse, NodeListItem, LogicalNodeResponse
+from .management_connection import ManagementConnection, ConnectionType
 
 __all__ = [
     ExternalValue,

acex_devkit-1.7.1/src/acex_devkit/models/management_connection.py

@@ -0,0 +1,16 @@
+from pydantic import BaseModel
+from typing import Optional
+from enum import Enum
+
+
+class ConnectionType(str, Enum):
+    ssh = "ssh"
+    telnet = "telnet"
+
+
+class ManagementConnection(BaseModel):
+    id: Optional[int] = None
+    node_id: Optional[int] = None
+    primary: bool = True
+    connection_type: ConnectionType = ConnectionType.ssh
+    target_ip: Optional[str] = None

acex_devkit-1.7.1/src/acex_devkit/normalizer/__init__.py

@@ -0,0 +1,22 @@
+"""Configuration normalizer — vendor-agnostic engine for stripping
+runtime noise and masking secrets from device configurations."""
+
+from acex_devkit.normalizer.engine import (
+    LineRule,
+    BlockRule,
+    RewriteRule,
+    OpStats,
+    OpResult,
+    NormalizerEngine,
+)
+from acex_devkit.normalizer.base import BaseNormalizer
+
+__all__ = [
+    "LineRule",
+    "BlockRule",
+    "RewriteRule",
+    "OpStats",
+    "OpResult",
+    "NormalizerEngine",
+    "BaseNormalizer",
+]

acex_devkit-1.7.1/src/acex_devkit/normalizer/base.py

@@ -0,0 +1,80 @@
+"""Base normalizer for vendor-specific subclasses.
+
+Subclasses only need to declare rules:
+
+    class MyVendorNormalizer(BaseNormalizer):
+        line_rules    = [...]
+        block_rules   = [...]
+        rewrite_rules = [...]
+
+Optional overrides if the vendor syntax differs:
+    is_block_continuation(line) -> bool
+    is_block_terminator(line)   -> bool
+    post_process(lines, stats)  -> list[str]
+"""
+
+from __future__ import annotations
+
+import re
+
+from acex_devkit.normalizer.engine import (
+    LineRule,
+    BlockRule,
+    RewriteRule,
+    OpStats,
+    OpResult,
+    NormalizerEngine,
+)
+
+
+class BaseNormalizer:
+    line_rules: list[LineRule] = []
+    block_rules: list[BlockRule] = []
+    rewrite_rules: list[RewriteRule] = []
+
+    engine: NormalizerEngine = NormalizerEngine()
+
+    # ── hooks (override per vendor) ───────────────────────────────
+
+    def is_block_continuation(self, line: str) -> bool:
+        if not line:
+            return False
+        if line.startswith((" ", "\t")):
+            return True
+        if re.fullmatch(r"[0-9A-Fa-f ]+", line.rstrip()):
+            return True
+        return False
+
+    def is_block_terminator(self, line: str) -> bool:
+        return line.strip() in ("quit", "exit")
+
+    def post_process(self, lines: list[str], stats: OpStats) -> list[str]:
+        return self.engine.collapse_and_trim(lines, stats)
+
+    # ── operations ────────────────────────────────────────────────
+
+    def normalize(self, raw: str) -> OpResult:
+        lines, stats = self.engine.normalize_pass(
+            raw,
+            line_rules=self.line_rules,
+            block_rules=self.block_rules,
+            is_block_continuation=self.is_block_continuation,
+            is_block_terminator=self.is_block_terminator,
+        )
+        lines = self.post_process(lines, stats)
+        stats.lines_out = len(lines)
+        return OpResult(
+            config="\n".join(lines) + ("\n" if lines else ""),
+            operation="normalize",
+            stats=stats,
+        )
+
+    def mask(self, raw: str) -> OpResult:
+        lines, stats = self.engine.mask_pass(
+            raw, rewrite_rules=self.rewrite_rules
+        )
+        return OpResult(
+            config="\n".join(lines) + ("\n" if lines else ""),
+            operation="mask",
+            stats=stats,
+        )

acex_devkit-1.7.1/src/acex_devkit/normalizer/engine.py

@@ -0,0 +1,162 @@
+"""Stateless rule engine and data types for config normalization.
+
+Two independent passes:
+    normalize_pass  — drops lines/blocks that are not intent-config
+    mask_pass       — rewrites lines to redact secrets
+
+The passes are isolated: normalize never touches content it keeps,
+mask never drops lines. This makes the operations order-independent.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+
+
+# ── Rule types ────────────────────────────────────────────────────────
+
+@dataclass(frozen=True)
+class LineRule:
+    """Matches a full line → the line is dropped."""
+    name: str
+    pattern: re.Pattern
+
+
+@dataclass(frozen=True)
+class BlockRule:
+    """Matches a block header → header + indented body are dropped."""
+    name: str
+    pattern: re.Pattern
+
+
+@dataclass(frozen=True)
+class RewriteRule:
+    """Rewrites a line (e.g. redact secrets)."""
+    name: str
+    pattern: re.Pattern
+    replacement: str
+
+
+# ── Result types ──────────────────────────────────────────────────────
+
+@dataclass
+class OpStats:
+    lines_in: int = 0
+    lines_out: int = 0
+    lines_dropped: int = 0
+    blocks_dropped: int = 0
+    lines_redacted: int = 0
+    by_rule: dict[str, int] = field(default_factory=dict)
+
+    def _bump(self, rule: str) -> None:
+        self.by_rule[rule] = self.by_rule.get(rule, 0) + 1
+
+
+@dataclass
+class OpResult:
+    config: str
+    operation: str  # "normalize" or "mask"
+    stats: OpStats
+
+
+# ── Engine ────────────────────────────────────────────────────────────
+
+class NormalizerEngine:
+    """Stateless rule engine used by BaseNormalizer subclasses."""
+
+    def normalize_pass(
+        self,
+        raw: str,
+        *,
+        line_rules: list[LineRule],
+        block_rules: list[BlockRule],
+        is_block_continuation,
+        is_block_terminator,
+    ) -> tuple[list[str], OpStats]:
+        stats = OpStats()
+        lines = raw.splitlines()
+        stats.lines_in = len(lines)
+        out: list[str] = []
+
+        i = 0
+        while i < len(lines):
+            line = lines[i]
+
+            block_hit = next(
+                (r for r in block_rules if r.pattern.match(line)), None
+            )
+            if block_hit:
+                stats.blocks_dropped += 1
+                stats._bump(f"block:{block_hit.name}")
+                stats.lines_dropped += 1
+                i += 1
+                while i < len(lines) and (
+                    is_block_continuation(lines[i])
+                    or is_block_terminator(lines[i])
+                ):
+                    stats.lines_dropped += 1
+                    i += 1
+                continue
+
+            line_hit = next(
+                (r for r in line_rules if r.pattern.match(line)), None
+            )
+            if line_hit:
+                stats.lines_dropped += 1
+                stats._bump(f"line:{line_hit.name}")
+                i += 1
+                continue
+
+            out.append(line)
+            i += 1
+
+        return out, stats
+
+    def mask_pass(
+        self,
+        raw: str,
+        *,
+        rewrite_rules: list[RewriteRule],
+    ) -> tuple[list[str], OpStats]:
+        stats = OpStats()
+        lines = raw.splitlines()
+        stats.lines_in = len(lines)
+        out: list[str] = []
+
+        for line in lines:
+            rewritten = line
+            for rule in rewrite_rules:
+                new = rule.pattern.sub(rule.replacement, rewritten)
+                if new != rewritten:
+                    stats.lines_redacted += 1
+                    stats._bump(f"redact:{rule.name}")
+                    rewritten = new
+                    break
+            out.append(rewritten)
+
+        stats.lines_out = len(out)
+        return out, stats
+
+    @staticmethod
+    def collapse_and_trim(
+        lines: list[str],
+        stats: OpStats,
+        comment_marker: str = "!",
+    ) -> list[str]:
+        collapsed: list[str] = []
+        prev_marker = False
+        for line in lines:
+            is_marker = line.strip() == comment_marker
+            if is_marker and prev_marker:
+                stats.lines_dropped += 1
+                stats._bump("post:collapse_comment")
+                continue
+            collapsed.append(line)
+            prev_marker = is_marker
+
+        while collapsed and collapsed[0].strip() in ("", comment_marker):
+            collapsed.pop(0)
+        while collapsed and collapsed[-1].strip() in ("", comment_marker):
+            collapsed.pop()
+        return collapsed