devaci 0.1.0__py3-none-any.whl

devaci/cobra/registry.py

@@ -0,0 +1,24 @@
+"""Explicit handler registry for Cobra object builders."""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+
+Handler = Callable[..., None]
+
+REGISTRY: dict[str, Handler] = {}
+
+
+def register(key: str) -> Callable[[Handler], Handler]:
+    """Register a builder function under a template/YAML key."""
+
+    def decorator(func: Handler) -> Handler:
+        REGISTRY[key] = func
+        return func
+
+    return decorator
+
+
+def get_handler(key: str) -> Handler | None:
+    """Return the handler registered under ``key``, or ``None``."""
+    return REGISTRY.get(key)

devaci/console.py

@@ -0,0 +1,34 @@
+"""Logging and console helpers for devaci."""
+
+from __future__ import annotations
+
+import logging
+
+from rich.console import Console
+from rich.syntax import Syntax
+
+logger = logging.getLogger("devaci")
+
+console = Console()
+
+
+def get_logger(name: str | None = None) -> logging.Logger:
+    """Return the devaci logger, or a child logger when ``name`` is given."""
+    return logger if name is None else logger.getChild(name)
+
+
+def configure_logging(level: int = logging.INFO) -> None:
+    """Attach a stream handler to the devaci logger (idempotent)."""
+    if logger.handlers:
+        return
+    handler = logging.StreamHandler()
+    handler.setFormatter(logging.Formatter("%(levelname)-8s %(name)s: %(message)s"))
+    logger.addHandler(handler)
+    logger.setLevel(level)
+
+
+def print_syntax(
+    content: str, lexer: str, theme: str = "fruity", line_numbers: bool = True
+) -> None:
+    """Pretty-print highlighted source (XML/JSON) to the terminal."""
+    console.print(Syntax(content, lexer, theme=theme, line_numbers=line_numbers))

devaci/data.py

@@ -0,0 +1,81 @@
+"""Input data loading (xlsx/csv) and filtering for devaci."""
+
+from __future__ import annotations
+
+import warnings
+from collections.abc import Iterable
+from pathlib import Path
+from typing import Any, cast
+
+import pandas as pd
+
+from devaci.exceptions import DataError
+
+
+def apply_filter(
+    df: pd.DataFrame,
+    column: str,
+    filters: Iterable[str] | None = None,
+) -> list[dict[str, Any]]:
+    """Filter a DataFrame by ``column`` and return a list of records.
+
+    When no ``filters`` are given, or the column is missing, all records are
+    returned. Empty and ``nan`` values are always excluded from filtering.
+    """
+    if not filters or not column or column not in df.columns:
+        if not filters:
+            return cast("list[dict[str, Any]]", df.to_dict("records"))
+        return []
+
+    series = df[column]
+    return cast(
+        "list[dict[str, Any]]",
+        df[series.notna() & series.astype(str).str.strip().ne("") & series.isin(filters)].to_dict(
+            orient="records"
+        ),
+    )
+
+
+def load_csv(
+    path: str | Path,
+    filters: Iterable[str] | None = None,
+    by: str = "tag",
+) -> dict[str, list[dict[str, Any]]]:
+    """Load a CSV file into ``{filename: [records]}``."""
+    path = Path(path)
+    df = pd.read_csv(path)
+    return {path.stem: apply_filter(df, by, filters)}
+
+
+def load_xlsx(
+    path: str | Path,
+    filters: Iterable[str] | None = None,
+    by: str = "tag",
+    filters_source_sheet: str | None = None,
+    filters_condition_field: str = "enabled",
+    filters_output_field: str = "name",
+) -> dict[str, list[dict[str, Any]]]:
+    """Load an XLSX workbook into ``{sheet_name: [records]}``.
+
+    Optionally derives the filter values from a dedicated sheet
+    (``filters_source_sheet``) using a boolean condition column.
+    """
+    path = Path(path)
+    with warnings.catch_warnings():
+        warnings.filterwarnings(
+            "ignore",
+            message="Data Validation extension is not supported*",
+            category=UserWarning,
+        )
+        sheets = pd.read_excel(path, sheet_name=None)
+
+    resolved_filters = filters
+    if filters_source_sheet:
+        df_filters = sheets.get(filters_source_sheet)
+        if df_filters is None:
+            raise DataError(f"Sheet '{filters_source_sheet}' does not exist in '{path}'!")
+        resolved_filters = df_filters.loc[
+            df_filters[filters_condition_field], filters_output_field
+        ].tolist()
+
+    return {name: apply_filter(df, by, resolved_filters) for name, df in sheets.items()}

devaci/deploy.py

@@ -0,0 +1,320 @@
+"""Deployment orchestrator for devaci."""
+
+from __future__ import annotations
+
+import contextlib
+import getpass
+import json
+import sys
+import time
+import xml.dom.minidom
+from datetime import datetime
+from pathlib import Path
+from typing import Any
+
+import cobra.mit.access
+import cobra.mit.session
+import urllib3
+
+from devaci.cobra import CobraBuilder
+from devaci.console import logger, print_syntax
+from devaci.data import load_csv, load_xlsx
+from devaci.exceptions import DeployError
+from devaci.jinja import JinjaRenderer
+from devaci.results import DeployResult
+
+urllib3.disable_warnings(urllib3.exceptions.InsecureRequestWarning)
+
+
+class DeployClass:
+    """Deployment manager for Cisco ACI using the Cobra SDK.
+
+    Handles the full workflow: template rendering, Cobra model rendering,
+    optional input filtering, output visualization/persistence, and optional
+    commit to APIC.
+
+    Configuration options:
+    - ip (str): APIC IPv4 address
+    - username (str): APIC username
+    - password (str): APIC password
+    - testing (bool): enable dry-run mode (default: False)
+    - filter_by (str): variable name used for filtering (default: "tag")
+    - timer (int): countdown in seconds before commit (default: 5)
+    - show_output (bool): pretty-print rendered output to the terminal
+    - file_output (str): output filename (JSON or XML)
+    - secure (bool): verify SSL certificates (default: False)
+    - render_to_xml (bool): render output as XML instead of JSON (default: True)
+    - working_folder (Path): base directory for templates and data files
+    - logging_output (str): logging filename (default: "outputs/logs/logging.json")
+    - logging (bool): enable execution logging to file
+    """
+
+    def __init__(self, **kwargs: Any) -> None:
+        self._testing = kwargs.get("testing", False)
+
+        self._ip = kwargs.get("ip")
+        self._username = kwargs.get("username")
+        self._password = kwargs.get("password")
+
+        if not self._testing:
+            if not self._ip:
+                self._ip = input("APIC IP Address: ").strip()
+            if not self._username:
+                self._username = input("APIC Username: ").strip()
+            if not self._password:
+                self._password = getpass.getpass("APIC Password: ")
+
+        self._url = f"https://{self._ip}" if self._ip else None
+        self._timeout = kwargs.get("timeout", 180)
+        self._secure = kwargs.get("secure", False)
+        self._timer = kwargs.get("timer", 5)
+        self._show_output = kwargs.get("show_output", False)
+        self._file_output = kwargs.get("file_output")
+        self._logging_output = kwargs.get("logging_output", "outputs/logs/logging.json")
+        self._logging = kwargs.get("logging", True)
+        self._render_to_xml = kwargs.get("render_to_xml", True)
+        self._filters_source_sheet = kwargs.get("filters_source_sheet")
+        self._filters_condition_field = kwargs.get("filters_condition_field", "enabled")
+        self._filters_output_field = kwargs.get("filters_output_field", "name")
+        self._filters = kwargs.get("filters")
+        self._filter_by = kwargs.get("filter_by", "tag")
+        self._working_folder: Path = kwargs.get("working_folder", Path.cwd())
+
+        self._cobra = CobraBuilder()
+        self._session = cobra.mit.session.LoginSession(
+            self._url, self._username, self._password, self._secure, self._timeout
+        )
+        self._modir = cobra.mit.access.MoDirectory(self._session)
+
+        self._template: list[tuple[str, Path]] = []
+        self._variables: dict[str, Any] = {}
+        self._results: list[dict[str, Any]] = []
+
+    # ------------------------------------------------------------------ Control
+
+    def deploy(self) -> None:
+        """Execute the deployment workflow for all configured templates."""
+        if not self._template:
+            logger.warning("[Deploy] -> [ConfigError]: No templates configured!")
+            return
+
+        for content, path in self._template:
+            self._results.append(self._deploy_one(content, path).to_dict())
+
+        if self._show_output:
+            self.print_output()
+
+        if self._file_output:
+            self.save_output(self._file_output)
+
+        if not self._testing and self._cobra.result is not None and self._cobra.result.success:
+            self._commit()
+
+        if self._logging:
+            self.save_logging()
+
+    def _deploy_one(self, content: str, path: Path) -> DeployResult:
+        name = path.name if isinstance(path, Path) else str(path)
+        logs: list[str] = []
+        success = False
+
+        try:
+            renderer = JinjaRenderer()
+            output = renderer.render(content, name=name, **self._variables)
+            logs.append(f"[Jinja]: Template {name} was rendered successfully.")
+            logger.info(logs[-1])
+
+            cobra_result = self._cobra.render(output)
+            logs.extend(cobra_result.log)
+            if not cobra_result.success:
+                raise DeployError(f"Template {name} failed to render Cobra objects.")
+
+            logs.append(f"[Deploy]: Template {name} was rendered successfully.")
+            logger.info(logs[-1])
+            success = True
+        except Exception as exc:
+            logs.append(f"[Deploy] -> [{type(exc).__name__}]: Failed to render template {name}.")
+            logger.error(
+                f"[Deploy] -> [{type(exc).__name__}]: Failed to render template {name}: {exc}"
+            )
+
+        return DeployResult(success=success, log=logs, path=str(path), name=name)
+
+    def _commit(self) -> None:
+        try:
+            self._countdown()
+            self._modir.login()
+            self._modir.commit(self._cobra.config)
+            msg = f"[Deploy]: Template was successfully deployed to APIC: {self._ip}."
+            logger.info(msg)
+            self._results.append(
+                {"date": datetime.now().strftime("%d/%m/%Y-%H:%M:%S"), "success": True, "log": msg}
+            )
+        except Exception as exc:
+            msg = f"[Deploy] -> [{type(exc).__name__}]: Unable to deploy to APIC: {self._ip}, {exc}"
+            logger.error(msg)
+            self._results.append(
+                {"date": datetime.now().strftime("%d/%m/%Y-%H:%M:%S"), "success": False, "log": msg}
+            )
+        finally:
+            with contextlib.suppress(Exception):
+                self._modir.logout()
+
+    def _countdown(self) -> None:
+        message = f"Deploying templates to APIC [{self._ip}] in"
+        for remaining in range(self._timer, -1, -1):
+            sys.stdout.write(f"\r{message} {remaining} seconds")
+            sys.stdout.flush()
+            time.sleep(1)
+        sys.stdout.write("\n")
+
+    # ------------------------------------------------------------------ Output
+
+    def save_output(self, name: str = "output") -> None:
+        """Save rendered configuration to disk (XML or JSON)."""
+        content = self.config
+        if content is None:
+            return
+
+        suffix = "xml" if self._render_to_xml else "json"
+        output_path = self._working_folder / f"{name}.{suffix}"
+        try:
+            if self._render_to_xml:
+                dom = xml.dom.minidom.parseString(content)
+                text = dom.toprettyxml(indent="\t")
+            else:
+                text = json.dumps(content, indent=4, ensure_ascii=False)
+            output_path.parent.mkdir(parents=True, exist_ok=True)
+            output_path.write_text(text, encoding="utf-8")
+        except Exception as exc:
+            logger.error(f"[SaveOutputError]: Failed to save output file! {exc}")
+
+    def print_output(self, theme: str = "fruity", line_numbers: bool = True) -> None:
+        """Pretty-print the rendered configuration to the terminal."""
+        content = self.config
+        if content is None:
+            return
+
+        try:
+            if self._render_to_xml:
+                text = xml.dom.minidom.parseString(content).toprettyxml(indent="\t")
+                lexer = "xml"
+            else:
+                text = json.dumps(content, indent=4, ensure_ascii=False)
+                lexer = "json"
+            print_syntax(text, lexer, theme=theme, line_numbers=line_numbers)
+        except Exception as exc:
+            logger.error(f"[PrintOutputError]: Error printing output! {exc}")
+
+    def save_logging(self) -> None:
+        """Append execution results to a JSON log file defensively."""
+        if not self._logging:
+            return
+
+        log_file = Path(self._working_folder / self._logging_output).with_suffix(".json")
+        history: list[Any] = []
+        try:
+            if log_file.exists():
+                try:
+                    with open(log_file, encoding="utf-8") as handle:
+                        history = json.load(handle)
+                        if not isinstance(history, list):
+                            history = []
+                except json.JSONDecodeError:
+                    history = []
+
+            history.extend(self._results)
+            log_file.parent.mkdir(parents=True, exist_ok=True)
+            with open(log_file, "w", encoding="utf-8") as handle:
+                json.dump(history, handle, indent=4, ensure_ascii=False)
+        except Exception as exc:
+            logger.error(f"[LoggingError]: {type(exc).__name__}: {exc}")
+
+    # ------------------------------------------------------------------ Properties
+
+    @property
+    def results(self) -> list[dict[str, Any]]:
+        return self._results
+
+    @property
+    def variables(self) -> dict[str, Any]:
+        return self._variables
+
+    @variables.setter
+    def variables(self, value: dict[str, Any]) -> None:
+        self._variables = value
+
+    @property
+    def template(self) -> list[tuple[str, Path]]:
+        return self._template
+
+    @template.setter
+    def template(self, value: Any) -> None:
+        """Load template content into memory.
+
+        Accepted inputs:
+        - str: template filename (loaded from working_folder)
+        - list[str]: multiple template filenames
+        - tuple[str, str]: (template_content, template_name)
+        - list[tuple[str, str]]: multiple in-memory templates
+        """
+        if not value:
+            return
+
+        values = value if isinstance(value, list) else [value]
+        for item in values:
+            try:
+                if isinstance(item, tuple) and len(item) == 2:
+                    content, name = item
+                    if not isinstance(content, str) or not isinstance(name, str):
+                        raise ValueError("Template content and name must be strings")
+                    self._template.append((content, Path(name)))
+                elif isinstance(item, str):
+                    path = self._working_folder / item
+                    with open(path, encoding="utf-8") as handle:
+                        self._template.append((handle.read(), path))
+                else:
+                    raise ValueError("Invalid template format")
+            except Exception as exc:
+                logger.error(f"[TemplateException]: Error loading template: {exc}")
+
+    @property
+    def config(self) -> Any:
+        return self._cobra.xml if self._render_to_xml else self._cobra.json
+
+    @property
+    def csv(self) -> dict[str, Any]:
+        return self._variables
+
+    @csv.setter
+    def csv(self, value: Any) -> None:
+        """Load CSV file(s) into the variables dict."""
+        files = [value] if isinstance(value, str) else value
+        for file in files:
+            try:
+                self._variables |= load_csv(
+                    self._working_folder / file, self._filters, self._filter_by
+                )
+            except Exception as exc:
+                logger.error(f"[CSVException]: Error loading CSV file: {exc}")
+
+    @property
+    def xlsx(self) -> dict[str, Any]:
+        return self._variables
+
+    @xlsx.setter
+    def xlsx(self, value: Any) -> None:
+        """Load XLSX file(s) into the variables dict."""
+        files = [value] if isinstance(value, str) else value
+        for file in files:
+            try:
+                self._variables |= load_xlsx(
+                    self._working_folder / file,
+                    self._filters,
+                    self._filter_by,
+                    self._filters_source_sheet,
+                    self._filters_condition_field,
+                    self._filters_output_field,
+                )
+            except Exception as exc:
+                logger.error(f"[XLSXException]: Error loading XLSX file '{file}': {exc}")

devaci/exceptions.py

@@ -0,0 +1,23 @@
+"""Exception hierarchy for devaci."""
+
+from __future__ import annotations
+
+
+class DevaciError(Exception):
+    """Base exception for all devaci errors."""
+
+
+class CobraError(DevaciError):
+    """Raised when building or committing Cobra model objects fails."""
+
+
+class JinjaError(DevaciError):
+    """Raised when rendering a Jinja template fails."""
+
+
+class DataError(DevaciError):
+    """Raised when loading input data (xlsx/csv) fails."""
+
+
+class DeployError(DevaciError):
+    """Raised when the deployment workflow fails."""

devaci/filters.py

@@ -0,0 +1,103 @@
+"""Jinja filters and YAML loading helpers for devaci."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from yaml import load
+from yaml.composer import Composer
+from yaml.constructor import SafeConstructor
+from yaml.parser import Parser
+from yaml.reader import Reader
+from yaml.resolver import Resolver
+from yaml.scanner import Scanner
+
+
+def split_filter(value: Any, delimiter: str = ",") -> list[str]:
+    """Split a value into a list of strings."""
+    return str(value).split(delimiter)
+
+
+def range_filter(value: Any) -> list[int]:
+    """Expand a string such as ``1-3,5`` into a list of integers."""
+    result: list[int] = []
+    for part in str(value).split(","):
+        if "-" in part:
+            start, end = part.split("-")
+            result.extend(range(int(start), int(end) + 1))
+        else:
+            result.append(int(part))
+    return result
+
+
+def nan_filter(value: Any) -> bool:
+    """Return False when the value is the string ``nan``."""
+    return str(value) != "nan"
+
+
+def str_to_bool(value: Any) -> bool:
+    """Convert common truthy strings to a boolean."""
+    if isinstance(value, bool):
+        return value
+    return str(value).lower() in ("true", "yes", "1")
+
+
+def no_convert_int_constructor(loader: Any, node: Any) -> Any:
+    """Keep YAML integers as their original string."""
+    return node.value
+
+
+def no_convert_float_constructor(loader: Any, node: Any) -> Any:
+    """Keep YAML floats as their original string."""
+    return node.value
+
+
+def replace_str_nan_with_empty(obj: Any) -> Any:
+    """Recursively replace string values equal to ``nan`` with ``""``."""
+    if isinstance(obj, dict):
+        return {k: replace_str_nan_with_empty(v) for k, v in obj.items()}
+    if isinstance(obj, list):
+        return [replace_str_nan_with_empty(v) for v in obj]
+    if isinstance(obj, str) and obj.strip().lower() == "nan":
+        return ""
+    return obj
+
+
+class _SafeConstructor(SafeConstructor):
+    pass
+
+
+def bool_constructor(loader: Any, node: Any) -> Any:
+    """Keep YAML booleans as their original string."""
+    return loader.construct_scalar(node)
+
+
+_SafeConstructor.add_constructor("tag:yaml.org,2002:bool", bool_constructor)
+
+
+class SafeLoader(Reader, Scanner, Parser, Composer, _SafeConstructor, Resolver):
+    """YAML loader that leaves int/float/bool values as strings."""
+
+    def __init__(self, stream: Any) -> None:
+        Reader.__init__(self, stream)
+        Scanner.__init__(self)
+        Parser.__init__(self)
+        Composer.__init__(self)
+        _SafeConstructor.__init__(self)
+        Resolver.__init__(self)
+
+
+SafeLoader.add_constructor("tag:yaml.org,2002:int", no_convert_int_constructor)
+SafeLoader.add_constructor("tag:yaml.org,2002:float", no_convert_float_constructor)
+
+for _first_char, _resolvers in list(SafeLoader.yaml_implicit_resolvers.items()):
+    _filtered = [r for r in _resolvers if r[0] != "tag:yaml.org,2002:bool"]
+    if _filtered:
+        SafeLoader.yaml_implicit_resolvers[_first_char] = _filtered
+    else:
+        del SafeLoader.yaml_implicit_resolvers[_first_char]
+
+
+def load_yaml(stream: Any) -> Any:
+    """Load YAML without type coercion and normalise ``nan`` strings."""
+    return replace_str_nan_with_empty(load(stream, SafeLoader))  # type: ignore[arg-type]

devaci/jinja.py

@@ -0,0 +1,42 @@
+"""Jinja2 template rendering for devaci."""
+
+from __future__ import annotations
+
+from typing import Any
+
+import jinja2
+
+from devaci.exceptions import JinjaError
+from devaci.filters import load_yaml, nan_filter, range_filter, str_to_bool
+
+
+class JinjaRenderer:
+    """Render a Jinja2 template into a Python dict.
+
+    The rendered output is expected to be YAML whose top-level keys map to
+    ACI object types (see :mod:`devaci.cobra`).
+    """
+
+    def __init__(self) -> None:
+        self._env = jinja2.Environment(
+            loader=jinja2.BaseLoader(),
+            extensions=["jinja2.ext.do"],
+        )
+        self._env.filters["bool"] = str_to_bool
+        self._env.filters["range"] = range_filter
+        self._env.filters["nan"] = nan_filter
+
+    def render(self, template: str, name: str | None = None, **variables: Any) -> dict[str, Any]:
+        """Render ``template`` with ``variables`` and parse the YAML output."""
+        try:
+            rendered = self._env.from_string(template).render(**variables)
+        except Exception as exc:
+            line = getattr(exc, "lineno", None)
+            raise JinjaError(f"[Jinja] -> [{type(exc).__name__}]: {exc}. Line: {line}") from exc
+
+        output = load_yaml(rendered)
+        if not isinstance(output, dict):
+            raise JinjaError(
+                f"[Jinja] -> [ConfigError]: Template {name} did not produce a mapping."
+            )
+        return output