devaci 2.0.0a1__tar.gz → 2.0.0a3__tar.gz

devaci-2.0.0a3/PKG-INFO

@@ -0,0 +1,228 @@
+Metadata-Version: 2.5
+Name: devaci
+Version: 2.0.0a3
+Summary: Python library that generates Cisco ACI configuration and optionally pushes it to an APIC controller via Cisco's official Cobra SDK.
+Project-URL: Homepage, https://github.com/cocuni80/devaci
+Project-URL: Repository, https://github.com/cocuni80/devaci
+Project-URL: Issues, https://github.com/cocuni80/devaci/issues
+Author: Jorge Riveros
+License: MIT
+License-File: LICENSE
+Keywords: aci,apic,cisco,cobra,networking,sdn
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: System Administrators
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: System :: Networking
+Requires-Python: >=3.10
+Requires-Dist: jinja2>=3.1.6
+Requires-Dist: openpyxl>=3.1.5
+Requires-Dist: pandas>=2.3.3
+Requires-Dist: pyyaml>=6.0.3
+Requires-Dist: rich>=15.0.0
+Requires-Dist: urllib3>=2.0
+Description-Content-Type: text/markdown
+
+# devaci
+
+Python library that generates Cisco ACI configuration from Jinja2 templates +
+Excel/CSV inputs, and optionally pushes it to an APIC controller via Cisco's
+official Cobra SDK.
+
+Pipeline: **data + template → `JinjaRenderer` (Jinja2 → YAML dict) →
+`CobraBuilder` (dict → `ConfigRequest`) → output / APIC commit**, orchestrated
+by `DeployClass`.
+
+## Requirements
+
+- Python 3.10+
+- The Cisco ACI **Cobra SDK** (`acicobra`, `acimodel`) — see below; it is
+  **not on PyPI**.
+
+## Installation
+
+```bash
+uv sync                 # create .venv, install devaci + dev dependencies
+source .venv/bin/activate
+```
+
+### External dependency: Cobra SDK
+
+The Cisco ACI Cobra SDK is distributed as `.whl`/`.egg` by Cisco and is **not
+on PyPI**. Download the wheels and place them in `vendor/` (not tracked by
+git), then:
+
+```bash
+uv pip install vendor/*.whl
+```
+
+The importable package is `cobra`. This repository vendors `acicobra` +
+`acimodel`; other Cisco modules are optional. `import devaci` (and therefore
+the whole test suite) fails until the SDK is installed.
+
+## Quick start
+
+```python
+from pathlib import Path
+
+from devaci import DeployClass
+
+aci = DeployClass(
+    testing=True,                 # True = dry run, no APIC credentials prompted
+    working_folder=Path.cwd(),    # base folder for templates/data/outputs
+    file_output="outputs/scripts/config",   # optional: save XML/JSON
+    show_output=False,            # print the rendered config to the terminal
+    logging=True,                 # append results to logging_output (JSON)
+)
+
+aci.xlsx = "data/aci.xlsx"        # load every sheet into template variables
+aci.template = "templates/tenant.j2"
+aci.deploy()
+
+print(aci.config)                 # rendered XML (or JSON dict)
+print(aci.results)                # per-template result dicts
+```
+
+`DeployClass` accepts either a typed `DeployConfig` or the keyword arguments
+shown above:
+
+```python
+from devaci import DeployConfig, DeployClass
+
+config = DeployConfig(testing=True, render_to_xml=False)
+aci = DeployClass(config=config)
+```
+
+With `testing=False` and no `ip`/`username`/`password`, the APIC credentials are
+prompted interactively (`getpass`). `deploy()` commits to the APIC **only when
+every template in the run succeeded**.
+
+## Templates
+
+A template is a Jinja2 file that renders to YAML. Each **top-level key maps to
+an ACI object class** handled by `CobraBuilder` (`fvTenant`, `fvAp`, `mcpInstPol`,
+`fabricNodeControl`, ...). Values may be a list of objects or a nested mapping:
+
+```jinja
+fvTenant:
+  - name: {{ tenant_name }}
+    descr: {{ tenant_descr }}
+    status: {{ status }}
+
+fvAp:
+  - name: web
+    fvRsCtx:
+      tnFvCtxName: {{ vrf }}
+```
+
+Rendering uses a **coercion-free YAML loader**: YAML ints/floats/bools are kept
+as strings so APIC values are never mangled, and the string `nan` becomes `""`.
+
+### Template filters
+
+| Filter        | Example                     | Result              |
+|---------------|-----------------------------|---------------------|
+| `bool`        | `{{ "yes" \| bool }}`       | `True`              |
+| `range`       | `{{ "1-3,5" \| range }}`    | `[1, 2, 3, 5]`      |
+| `nan`         | `{{ value \| nan }}`        | `False` when `nan`  |
+| `split`       | `{{ "a,b" \| split }}`      | `["a", "b"]`        |
+
+## Data inputs (XLSX / CSV)
+
+Both `aci.xlsx` and `aci.csv` accept a filename or a list of filenames:
+
+- An **XLSX** workbook loads one variable per **sheet**, named after the sheet.
+- A **CSV** file loads one variable named after the file **stem**.
+
+Each variable is a list of row dicts, so a sheet named `tenants` is used as
+`{% for row in tenants %}`.
+
+### Filtering
+
+- `filters`: list of values to keep, matched against the `filter_by` column
+  (default `tag`). Rows with empty/`NaN` tags are always dropped.
+- `filters_source_sheet`: derive the filter values from a dedicated sheet. Rows
+  where `filters_condition_field` (default `enabled`) is truthy contribute their
+  `filters_output_field` (default `name`) as a filter value.
+
+```python
+aci = DeployClass(
+    testing=True,
+    filters=["IBK-6", "IBK-7"],
+    filter_by="tag",
+    filters_source_sheet="OCs",       # optional
+    filters_condition_field="enabled",
+    filters_output_field="name",
+)
+```
+
+## Output
+
+- `render_to_xml=True` (default): config is XML (`.xml`); otherwise JSON (`.json`).
+- `file_output="outputs/scripts/config"`: write the rendered config to disk.
+- `show_output=True`: pretty-print the rendered config to the terminal.
+- `save_output(name)` / `print_output()` can be called directly.
+
+## Logging
+
+devaci uses the standard library `logging` module. It attaches a
+`NullHandler` on import (no output by default); opt in with the public
+`configure_logging()`:
+
+```python
+import logging
+from devaci import configure_logging
+
+configure_logging(level=logging.INFO)   # idempotent; adds one stream handler
+```
+
+Module loggers are exposed as `devaci.<module>` (e.g. `devaci.deploy`) and
+propagate to the stdlib root logger, so per-module levels can be tuned with
+normal logging configuration. Terminal output of rendered configuration and the
+APIC countdown go through the shared rich console in `devaci.console`.
+
+> `RunLog` (`logging_output`, default `outputs/logs/logging.json`) is a JSON
+> **execution history**, not stdlib logging. Disable with `logging=False`.
+
+## Project structure
+
+```
+src/devaci/
+├── __init__.py        # public API
+├── config.py          # typed DeployConfig
+├── console.py         # centralized logging + shared rich console
+├── deploy.py          # DeployClass orchestrator
+├── exceptions.py
+├── results.py         # result dataclasses
+├── _values.py         # shared value predicates (nan/empty checks)
+├── inputs/            # TemplateSource + DataLoader (xlsx/csv, filters)
+├── rendering/         # JinjaRenderer, filters, non-coercing YAML loader
+├── output/            # OutputWriter + RunLog
+├── transport/         # ApicSession (login/commit)
+└── cobra/             # CobraBuilder + BUILDERS mapping
+```
+
+## Development
+
+```bash
+uv run pytest                 # full test suite
+uv run pytest --cov=devaci    # with coverage (fails under 80%)
+uv run ruff check .           # lint
+uv run mypy src               # typecheck (strict)
+```
+
+Run order when verifying a change: `ruff check .` → `mypy src` → `pytest`.
+
+## Publishing
+
+```bash
+uv build
+uv publish
+```
+
+Only a PyPI release bumps the version; commits do not. See `CONTRIBUTING.md`.

devaci-2.0.0a3/README.md

@@ -0,0 +1,198 @@
+# devaci
+
+Python library that generates Cisco ACI configuration from Jinja2 templates +
+Excel/CSV inputs, and optionally pushes it to an APIC controller via Cisco's
+official Cobra SDK.
+
+Pipeline: **data + template → `JinjaRenderer` (Jinja2 → YAML dict) →
+`CobraBuilder` (dict → `ConfigRequest`) → output / APIC commit**, orchestrated
+by `DeployClass`.
+
+## Requirements
+
+- Python 3.10+
+- The Cisco ACI **Cobra SDK** (`acicobra`, `acimodel`) — see below; it is
+  **not on PyPI**.
+
+## Installation
+
+```bash
+uv sync                 # create .venv, install devaci + dev dependencies
+source .venv/bin/activate
+```
+
+### External dependency: Cobra SDK
+
+The Cisco ACI Cobra SDK is distributed as `.whl`/`.egg` by Cisco and is **not
+on PyPI**. Download the wheels and place them in `vendor/` (not tracked by
+git), then:
+
+```bash
+uv pip install vendor/*.whl
+```
+
+The importable package is `cobra`. This repository vendors `acicobra` +
+`acimodel`; other Cisco modules are optional. `import devaci` (and therefore
+the whole test suite) fails until the SDK is installed.
+
+## Quick start
+
+```python
+from pathlib import Path
+
+from devaci import DeployClass
+
+aci = DeployClass(
+    testing=True,                 # True = dry run, no APIC credentials prompted
+    working_folder=Path.cwd(),    # base folder for templates/data/outputs
+    file_output="outputs/scripts/config",   # optional: save XML/JSON
+    show_output=False,            # print the rendered config to the terminal
+    logging=True,                 # append results to logging_output (JSON)
+)
+
+aci.xlsx = "data/aci.xlsx"        # load every sheet into template variables
+aci.template = "templates/tenant.j2"
+aci.deploy()
+
+print(aci.config)                 # rendered XML (or JSON dict)
+print(aci.results)                # per-template result dicts
+```
+
+`DeployClass` accepts either a typed `DeployConfig` or the keyword arguments
+shown above:
+
+```python
+from devaci import DeployConfig, DeployClass
+
+config = DeployConfig(testing=True, render_to_xml=False)
+aci = DeployClass(config=config)
+```
+
+With `testing=False` and no `ip`/`username`/`password`, the APIC credentials are
+prompted interactively (`getpass`). `deploy()` commits to the APIC **only when
+every template in the run succeeded**.
+
+## Templates
+
+A template is a Jinja2 file that renders to YAML. Each **top-level key maps to
+an ACI object class** handled by `CobraBuilder` (`fvTenant`, `fvAp`, `mcpInstPol`,
+`fabricNodeControl`, ...). Values may be a list of objects or a nested mapping:
+
+```jinja
+fvTenant:
+  - name: {{ tenant_name }}
+    descr: {{ tenant_descr }}
+    status: {{ status }}
+
+fvAp:
+  - name: web
+    fvRsCtx:
+      tnFvCtxName: {{ vrf }}
+```
+
+Rendering uses a **coercion-free YAML loader**: YAML ints/floats/bools are kept
+as strings so APIC values are never mangled, and the string `nan` becomes `""`.
+
+### Template filters
+
+| Filter        | Example                     | Result              |
+|---------------|-----------------------------|---------------------|
+| `bool`        | `{{ "yes" \| bool }}`       | `True`              |
+| `range`       | `{{ "1-3,5" \| range }}`    | `[1, 2, 3, 5]`      |
+| `nan`         | `{{ value \| nan }}`        | `False` when `nan`  |
+| `split`       | `{{ "a,b" \| split }}`      | `["a", "b"]`        |
+
+## Data inputs (XLSX / CSV)
+
+Both `aci.xlsx` and `aci.csv` accept a filename or a list of filenames:
+
+- An **XLSX** workbook loads one variable per **sheet**, named after the sheet.
+- A **CSV** file loads one variable named after the file **stem**.
+
+Each variable is a list of row dicts, so a sheet named `tenants` is used as
+`{% for row in tenants %}`.
+
+### Filtering
+
+- `filters`: list of values to keep, matched against the `filter_by` column
+  (default `tag`). Rows with empty/`NaN` tags are always dropped.
+- `filters_source_sheet`: derive the filter values from a dedicated sheet. Rows
+  where `filters_condition_field` (default `enabled`) is truthy contribute their
+  `filters_output_field` (default `name`) as a filter value.
+
+```python
+aci = DeployClass(
+    testing=True,
+    filters=["IBK-6", "IBK-7"],
+    filter_by="tag",
+    filters_source_sheet="OCs",       # optional
+    filters_condition_field="enabled",
+    filters_output_field="name",
+)
+```
+
+## Output
+
+- `render_to_xml=True` (default): config is XML (`.xml`); otherwise JSON (`.json`).
+- `file_output="outputs/scripts/config"`: write the rendered config to disk.
+- `show_output=True`: pretty-print the rendered config to the terminal.
+- `save_output(name)` / `print_output()` can be called directly.
+
+## Logging
+
+devaci uses the standard library `logging` module. It attaches a
+`NullHandler` on import (no output by default); opt in with the public
+`configure_logging()`:
+
+```python
+import logging
+from devaci import configure_logging
+
+configure_logging(level=logging.INFO)   # idempotent; adds one stream handler
+```
+
+Module loggers are exposed as `devaci.<module>` (e.g. `devaci.deploy`) and
+propagate to the stdlib root logger, so per-module levels can be tuned with
+normal logging configuration. Terminal output of rendered configuration and the
+APIC countdown go through the shared rich console in `devaci.console`.
+
+> `RunLog` (`logging_output`, default `outputs/logs/logging.json`) is a JSON
+> **execution history**, not stdlib logging. Disable with `logging=False`.
+
+## Project structure
+
+```
+src/devaci/
+├── __init__.py        # public API
+├── config.py          # typed DeployConfig
+├── console.py         # centralized logging + shared rich console
+├── deploy.py          # DeployClass orchestrator
+├── exceptions.py
+├── results.py         # result dataclasses
+├── _values.py         # shared value predicates (nan/empty checks)
+├── inputs/            # TemplateSource + DataLoader (xlsx/csv, filters)
+├── rendering/         # JinjaRenderer, filters, non-coercing YAML loader
+├── output/            # OutputWriter + RunLog
+├── transport/         # ApicSession (login/commit)
+└── cobra/             # CobraBuilder + BUILDERS mapping
+```
+
+## Development
+
+```bash
+uv run pytest                 # full test suite
+uv run pytest --cov=devaci    # with coverage (fails under 80%)
+uv run ruff check .           # lint
+uv run mypy src               # typecheck (strict)
+```
+
+Run order when verifying a change: `ruff check .` → `mypy src` → `pytest`.
+
+## Publishing
+
+```bash
+uv build
+uv publish
+```
+
+Only a PyPI release bumps the version; commits do not. See `CONTRIBUTING.md`.

{devaci-2.0.0a1 → devaci-2.0.0a3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "devaci"
-version = "2.0.0a1"
+version = "2.0.0a3"
 description = "Python library that generates Cisco ACI configuration and optionally pushes it to an APIC controller via Cisco's official Cobra SDK."
 readme = "README.md"
 requires-python = ">=3.10"
@@ -34,6 +34,7 @@ dependencies = [
     "pandas>=2.3.3",
     "pyyaml>=6.0.3",
     "rich>=15.0.0",
+    "urllib3>=2.0",
 ]
 
 [dependency-groups]
@@ -52,11 +53,9 @@ Issues = "https://github.com/cocuni80/devaci/issues"
 
 [tool.hatch.build.targets.wheel]
 packages = ["src/devaci"]
-exclude = ["src/devaci/_legacy"]
 
 [tool.hatch.build.targets.sdist]
 include = ["src/devaci", "tests", "README.md", "LICENSE"]
-exclude = ["src/devaci/_legacy"]
 
 [tool.pytest.ini_options]
 testpaths = ["tests"]
@@ -64,29 +63,30 @@ addopts = "-ra"
 
 [tool.coverage.run]
 source = ["devaci"]
-omit = ["*/_legacy/*"]
+# builders.py is a large map of thin Cobra SDK wrappers, exercised through the
+# end-to-end deploy path rather than unit tests; it is excluded from the gate.
+omit = ["*/cobra/builders.py"]
 
 [tool.coverage.report]
 show_missing = true
+fail_under = 80
 
 [tool.ruff]
 target-version = "py310"
 line-length = 100
-exclude = ["src/devaci/_legacy"]
 
 [tool.ruff.lint]
 select = ["E", "F", "I", "N", "UP", "B", "SIM"]
 
 [tool.ruff.lint.per-file-ignores]
 # Cobra SDK convention uses PascalCase locals mirroring Mo class names,
-# and the legacy handlers use nested `if` guards (kept verbatim).
+# and the handlers use nested `if` guards (kept verbatim).
 "src/devaci/cobra/builders.py" = ["N806", "SIM102"]
 
 [tool.mypy]
 python_version = "3.10"
 strict = true
 files = ["src"]
-exclude = ["_legacy"]
 
 [[tool.mypy.overrides]]
 module = ["cobra", "cobra.*", "jinja2", "pandas"]

{devaci-2.0.0a1 → devaci-2.0.0a3}/src/devaci/__init__.py

@@ -3,9 +3,11 @@
 from importlib.metadata import PackageNotFoundError, version
 
 from devaci.cobra import CobraBuilder
+from devaci.config import DeployConfig
+from devaci.console import configure_logging
 from devaci.deploy import DeployClass
 from devaci.exceptions import CobraError, DataError, DeployError, DevaciError, JinjaError
-from devaci.jinja import JinjaRenderer
+from devaci.rendering.jinja import JinjaRenderer
 
 try:
     __version__ = version("devaci")
@@ -15,7 +17,9 @@ except PackageNotFoundError:
 __all__ = [
     "CobraBuilder",
     "DeployClass",
+    "DeployConfig",
     "JinjaRenderer",
+    "configure_logging",
     "DevaciError",
     "CobraError",
     "JinjaError",

devaci-2.0.0a3/src/devaci/_values.py

@@ -0,0 +1,31 @@
+"""Internal value predicates shared across devaci layers."""
+
+from __future__ import annotations
+
+from math import isnan
+from typing import Any
+
+__all__ = ["is_invalid", "is_nan", "is_nan_text"]
+
+
+def is_nan_text(value: Any) -> bool:
+    """Return True when ``value`` is the text ``nan`` (case-insensitive, stripped)."""
+    return isinstance(value, str) and value.strip().lower() == "nan"
+
+
+def is_nan(value: Any) -> bool:
+    """Return True for a float NaN or the text ``nan`` (case-insensitive)."""
+    if isinstance(value, float):
+        return isnan(value)
+    return is_nan_text(value)
+
+
+def is_invalid(value: Any) -> bool:
+    """Return True for None, empty/whitespace strings, text ``nan`` or float NaN."""
+    if value is None:
+        return True
+    if is_nan(value):
+        return True
+    if isinstance(value, str):
+        return not value.strip()
+    return False

{devaci-2.0.0a1 → devaci-2.0.0a3}/src/devaci/cobra/__init__.py

@@ -2,16 +2,18 @@
 
 from __future__ import annotations
 
-import json
-from typing import Any, cast
+from typing import Any
 
 import cobra.mit.request
 import cobra.model.pol
 
-from devaci.cobra.registry import REGISTRY
-from devaci.console import logger
+from devaci.cobra.base import config_json, config_xml
+from devaci.cobra.builders import BUILDERS
+from devaci.console import get_logger
 from devaci.results import CobraResult
 
+logger = get_logger(__name__)
+
 
 class CobraBuilder:
     """Build an ACI configuration (:class:`ConfigRequest`) from a rendered dict.
@@ -20,6 +22,12 @@ class CobraBuilder:
     :mod:`devaci.cobra.builders`). Each handler receives the builder and the
     list of objects and is responsible for adding Mo instances to
     :attr:`config`.
+
+    A builder is **cumulative**: every object added by :meth:`render` stays in
+    the same :class:`ConfigRequest` rooted at :attr:`uni`, so several renders
+    (e.g. several templates) build one tree that is committed once. To start a
+    fresh tree, create a new :class:`CobraBuilder`; devaci never clears the
+    accumulated tree.
     """
 
     def __init__(self) -> None:
@@ -40,13 +48,13 @@ class CobraBuilder:
 
     @property
     def xml(self) -> str | None:
-        """Return the rendered XML payload."""
-        return cast(str | None, self.config.xmldata)
+        """Return the rendered XML payload, or None when the config is empty."""
+        return config_xml(self.config)
 
     @property
-    def json(self) -> Any:
-        """Return the rendered JSON payload as a dict."""
-        return json.loads(self.config.data)
+    def json(self) -> dict[str, Any] | None:
+        """Return the rendered JSON payload as a dict, or None when the config is empty."""
+        return config_json(self.config)
 
     def render(self, output: dict[str, Any]) -> CobraResult:
         """Render ``output`` through the registered handlers.
@@ -61,33 +69,30 @@ class CobraBuilder:
             if value in (None, [], {}, ""):
                 continue
 
-            handler = REGISTRY.get(key)
+            handler = BUILDERS.get(key)
             if handler is None:
                 success = False
-                msg = f"[Cobra] -> [ConfigError]: Class {key} does not exist."
-                logger.warning(msg)
+                msg = f"Class {key} does not exist."
+                logger.warning("%s", msg)
                 logs.append(msg)
                 continue
 
             try:
                 handler(self, value)
-                msg = f"[Cobra]: Class {key} was rendered successfully."
-                logger.info(msg)
+                msg = f"Class {key} rendered successfully."
+                logger.info("%s", msg)
                 logs.append(msg)
             except Exception as exc:
                 success = False
-                msg = f"[Cobra] -> [{type(exc).__name__}]: Class {key} failed: {exc}"
-                logger.error(msg)
+                msg = f"Class {key} failed: {exc}"
+                logger.exception("%s", msg)
                 logs.append(msg)
 
         if not self.config.configMos:
             success = False
-            msg = "[Cobra] -> [ConfigError]: No object was found in configuration."
-            logger.warning(msg)
+            msg = "No object was found in configuration."
+            logger.warning("%s", msg)
             logs.append(msg)
 
         self.result = CobraResult(success=success, log=logs, config=self.config)
         return self.result
-
-
-from devaci.cobra import builders  # noqa: E402, F401

devaci-2.0.0a3/src/devaci/cobra/base.py

@@ -0,0 +1,46 @@
+"""Shared helpers for Cobra object builders."""
+
+from __future__ import annotations
+
+import json
+from collections.abc import Iterable, Mapping
+from typing import TYPE_CHECKING, Any, Protocol, cast
+
+from devaci._values import is_invalid
+
+if TYPE_CHECKING:
+    from devaci.cobra import CobraBuilder
+
+
+class Handler(Protocol):
+    """A registered handler for one top-level ACI object key."""
+
+    def __call__(self, builder: CobraBuilder, value: Any) -> None: ...
+
+
+def not_nan_str(value: Mapping[str, Any], keys: Iterable[str]) -> bool:
+    """Return True when none of the given keys hold an invalid value.
+
+    A value is considered invalid when it is ``None``, an empty/whitespace
+    string, the string ``nan`` (case-insensitive), or a float NaN. Missing
+    keys are ignored.
+    """
+    return not any(is_invalid(value[k]) for k in keys if k in value)
+
+
+def _has_objects(config: Any) -> bool:
+    return config is not None and bool(config.configMos)
+
+
+def config_xml(config: Any) -> str | None:
+    """Return the XML payload of a ``ConfigRequest``, or None when empty."""
+    if not _has_objects(config):
+        return None
+    return cast("str | None", config.xmldata)
+
+
+def config_json(config: Any) -> dict[str, Any] | None:
+    """Return the JSON-decoded payload of a ``ConfigRequest``, or None when empty."""
+    if not _has_objects(config):
+        return None
+    return cast("dict[str, Any]", json.loads(config.data))