zbxtemplar 0.1.0__tar.gz

zbxtemplar-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Aleksei Dorozhkin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

zbxtemplar-0.1.0/PKG-INFO

@@ -0,0 +1,229 @@
+Metadata-Version: 2.4
+Name: zbxtemplar
+Version: 0.1.0
+Summary: Programmatic Zabbix template generation — Monitoring as Code
+Author: Aleksei Dorozhkin
+License: MIT License
+        
+        Copyright (c) 2026 Aleksei Dorozhkin
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+        
+Project-URL: Homepage, https://github.com/mithraelle/zbxtemplar
+Project-URL: Bug Tracker, https://github.com/mithraelle/zbxtemplar/issues
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: System Administrators
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: System :: Monitoring
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pyyaml>=6.0
+Dynamic: license-file
+
+# zbxtemplar
+
+A Pythonic framework for programmatic Zabbix Template generation (Monitoring as Code).
+
+The goal is to cover the essential Zabbix configuration primitives — not every possible option. If you need a field that isn't exposed, raw dicts and string expressions give you an escape hatch.
+
+## Installation
+
+```bash
+pip install .
+```
+
+## Core Architecture
+
+The project follows the `src-layout`:
+
+- `zbxtemplar.entities` — Domain models: Template, Item, Trigger, Graph, Dashboard.
+- `zbxtemplar.core` — Module contract (`TemplarModule`), loader, serialization, shared types.
+- `zbxtemplar.main` — CLI entry point.
+
+## Module Contract
+
+Templates are defined as Python classes that inherit from `TemplarModule`.
+The constructor is the contract — all template logic lives in `__init__`.
+
+```python
+from zbxtemplar.core import TemplarModule
+from zbxtemplar.entities import Template, Item, Trigger, TriggerPriority, Graph
+
+class MyTemplate(TemplarModule):
+    def __init__(self):
+        super().__init__()
+
+        template = Template(name="My Service")
+        template.add_tag("Service", "MyApp")
+        template.add_macro("THRESHOLD", 90, "Alert threshold")
+
+        item = Item("CPU Usage", "system.cpu.util")
+        item.add_trigger("High CPU", "last", ">",
+                         template.get_macro("THRESHOLD"),
+                         priority=TriggerPriority.HIGH)
+        template.add_item(item)
+
+        self.templates = [template]
+        self.triggers = []
+        self.graphs = []
+```
+
+A module file can contain multiple `TemplarModule` subclasses.
+The loader discovers all of them by class name.
+
+### Running standalone
+
+Add a `__main__` guard to run the module directly:
+
+```python
+if __name__ == "__main__":
+    import yaml
+    module = MyTemplate()
+    print(yaml.dump(module.to_export(), default_flow_style=False, sort_keys=False))
+```
+
+## CLI
+
+```bash
+# Basic usage
+zbxtemplar module.py output.yml
+python -m zbxtemplar module.py output.yml
+
+# With options
+zbxtemplar module.py output.yml \
+    --namespace "My Company" \
+    --template-group "Custom Templates"
+```
+
+| Argument | Description |
+|---|---|
+| `module` | Path to a `.py` file with `TemplarModule` subclass(es) |
+| `output` | Output YAML file path |
+| `--namespace` | UUID namespace for deterministic ID generation |
+| `--template-group` | Default template group name |
+
+## Programmatic Loading
+
+```python
+from zbxtemplar.core import load_module
+
+modules = load_module("path/to/module.py")
+# Returns {"ClassName": <instance>, ...}
+
+for name, mod in modules.items():
+    export = mod.to_export()  # Full zabbix_export dict
+```
+
+## Entities Reference
+
+### Template
+
+```python
+template = Template(name="My Template", groups=["Custom Group"])
+template.add_tag("Service", "MyApp")
+template.add_macro("TIMEOUT", 30, "Connection timeout")
+template.add_item(item)
+```
+
+### Item
+
+```python
+item = Item("CPU Usage", "system.cpu.util")
+
+# Expression helper — builds Zabbix function strings
+item.expr("last")            # last(/host/key)
+item.expr("min", "10m")      # min(/host/key,10m)
+item.expr("count", "#10")    # count(/host/key,#10)
+
+# Single-item trigger shorthand
+item.add_trigger("High CPU", "last", ">", 90,
+                 priority=TriggerPriority.HIGH,
+                 description="CPU threshold exceeded")
+
+# With function args
+item.add_trigger("Sustained high", "min", ">", 100,
+                 fn_args=("10m",), priority=TriggerPriority.WARNING)
+```
+
+All enum values (`ItemType`, `ValueType`, `TriggerPriority`, `GraphType`, `DrawType`, `CalcFnc`, etc.) follow the Zabbix export format documentation.
+
+### Trigger
+
+```python
+# Standalone (multi-item) trigger — raw expression string
+Trigger(name="Complex alert",
+        expression=item1.expr("last") + ">0 and " + item2.expr("min", "5m") + "<100",
+        priority=TriggerPriority.WARNING,
+        description="Multi-item condition")
+```
+
+### Macro
+
+Macros work seamlessly in string contexts:
+
+```python
+template.add_macro("MY_MACRO", 1, "Description")
+macro = template.get_macro("MY_MACRO")
+
+str(macro)                    # {$MY_MACRO}
+item.expr("last") + ">" + macro  # last(/host/key)>{$MY_MACRO}
+item.add_trigger("Alert", "last", ">", macro)  # works as threshold
+```
+
+### Graph
+
+```python
+graph = Graph("CPU Graph",
+              graph_type=GraphType.STACKED,
+              y_min_type=YAxisType.FIXED, y_min=0,
+              y_max_type=YAxisType.FIXED, y_max=100)
+
+graph.add_item(item1, "FF0000")
+graph.add_item(item2, "00FF00",
+               drawtype=DrawType.BOLD_LINE,
+               calc_fnc=CalcFnc.MAX,
+               yaxisside=YAxisSide.RIGHT)
+```
+
+### Dashboard
+
+```python
+from zbxtemplar.entities import Dashboard, DashboardPage
+from zbxtemplar.entities.DashboardWidget import ClassicGraph
+
+page = DashboardPage(name="Overview", display_period=120)
+page.add_widget(ClassicGraph(host=template.name, graph=graph, width=36, height=5))
+
+dashboard = Dashboard("My Dashboard", display_period=60, auto_start=YesNo.NO)
+dashboard.add_page(page)
+template.add_dashboard(dashboard)
+```
+
+Widgets are concrete subclasses of `Widget` (abstract). Each widget type lives in `zbxtemplar.entities.DashboardWidget`. Creating custom widgets is straightforward — subclass `Widget`, define `type` and `widget_fields()`.
+
+## Global Configuration
+
+```python
+from zbxtemplar.core.ZbxEntity import set_uuid_namespace, set_template_group
+
+set_uuid_namespace("My Company")    # Deterministic UUIDs scoped to namespace
+set_template_group("My Templates")  # Default group for new templates
+```

zbxtemplar-0.1.0/README.md

@@ -0,0 +1,189 @@
+# zbxtemplar
+
+A Pythonic framework for programmatic Zabbix Template generation (Monitoring as Code).
+
+The goal is to cover the essential Zabbix configuration primitives — not every possible option. If you need a field that isn't exposed, raw dicts and string expressions give you an escape hatch.
+
+## Installation
+
+```bash
+pip install .
+```
+
+## Core Architecture
+
+The project follows the `src-layout`:
+
+- `zbxtemplar.entities` — Domain models: Template, Item, Trigger, Graph, Dashboard.
+- `zbxtemplar.core` — Module contract (`TemplarModule`), loader, serialization, shared types.
+- `zbxtemplar.main` — CLI entry point.
+
+## Module Contract
+
+Templates are defined as Python classes that inherit from `TemplarModule`.
+The constructor is the contract — all template logic lives in `__init__`.
+
+```python
+from zbxtemplar.core import TemplarModule
+from zbxtemplar.entities import Template, Item, Trigger, TriggerPriority, Graph
+
+class MyTemplate(TemplarModule):
+    def __init__(self):
+        super().__init__()
+
+        template = Template(name="My Service")
+        template.add_tag("Service", "MyApp")
+        template.add_macro("THRESHOLD", 90, "Alert threshold")
+
+        item = Item("CPU Usage", "system.cpu.util")
+        item.add_trigger("High CPU", "last", ">",
+                         template.get_macro("THRESHOLD"),
+                         priority=TriggerPriority.HIGH)
+        template.add_item(item)
+
+        self.templates = [template]
+        self.triggers = []
+        self.graphs = []
+```
+
+A module file can contain multiple `TemplarModule` subclasses.
+The loader discovers all of them by class name.
+
+### Running standalone
+
+Add a `__main__` guard to run the module directly:
+
+```python
+if __name__ == "__main__":
+    import yaml
+    module = MyTemplate()
+    print(yaml.dump(module.to_export(), default_flow_style=False, sort_keys=False))
+```
+
+## CLI
+
+```bash
+# Basic usage
+zbxtemplar module.py output.yml
+python -m zbxtemplar module.py output.yml
+
+# With options
+zbxtemplar module.py output.yml \
+    --namespace "My Company" \
+    --template-group "Custom Templates"
+```
+
+| Argument | Description |
+|---|---|
+| `module` | Path to a `.py` file with `TemplarModule` subclass(es) |
+| `output` | Output YAML file path |
+| `--namespace` | UUID namespace for deterministic ID generation |
+| `--template-group` | Default template group name |
+
+## Programmatic Loading
+
+```python
+from zbxtemplar.core import load_module
+
+modules = load_module("path/to/module.py")
+# Returns {"ClassName": <instance>, ...}
+
+for name, mod in modules.items():
+    export = mod.to_export()  # Full zabbix_export dict
+```
+
+## Entities Reference
+
+### Template
+
+```python
+template = Template(name="My Template", groups=["Custom Group"])
+template.add_tag("Service", "MyApp")
+template.add_macro("TIMEOUT", 30, "Connection timeout")
+template.add_item(item)
+```
+
+### Item
+
+```python
+item = Item("CPU Usage", "system.cpu.util")
+
+# Expression helper — builds Zabbix function strings
+item.expr("last")            # last(/host/key)
+item.expr("min", "10m")      # min(/host/key,10m)
+item.expr("count", "#10")    # count(/host/key,#10)
+
+# Single-item trigger shorthand
+item.add_trigger("High CPU", "last", ">", 90,
+                 priority=TriggerPriority.HIGH,
+                 description="CPU threshold exceeded")
+
+# With function args
+item.add_trigger("Sustained high", "min", ">", 100,
+                 fn_args=("10m",), priority=TriggerPriority.WARNING)
+```
+
+All enum values (`ItemType`, `ValueType`, `TriggerPriority`, `GraphType`, `DrawType`, `CalcFnc`, etc.) follow the Zabbix export format documentation.
+
+### Trigger
+
+```python
+# Standalone (multi-item) trigger — raw expression string
+Trigger(name="Complex alert",
+        expression=item1.expr("last") + ">0 and " + item2.expr("min", "5m") + "<100",
+        priority=TriggerPriority.WARNING,
+        description="Multi-item condition")
+```
+
+### Macro
+
+Macros work seamlessly in string contexts:
+
+```python
+template.add_macro("MY_MACRO", 1, "Description")
+macro = template.get_macro("MY_MACRO")
+
+str(macro)                    # {$MY_MACRO}
+item.expr("last") + ">" + macro  # last(/host/key)>{$MY_MACRO}
+item.add_trigger("Alert", "last", ">", macro)  # works as threshold
+```
+
+### Graph
+
+```python
+graph = Graph("CPU Graph",
+              graph_type=GraphType.STACKED,
+              y_min_type=YAxisType.FIXED, y_min=0,
+              y_max_type=YAxisType.FIXED, y_max=100)
+
+graph.add_item(item1, "FF0000")
+graph.add_item(item2, "00FF00",
+               drawtype=DrawType.BOLD_LINE,
+               calc_fnc=CalcFnc.MAX,
+               yaxisside=YAxisSide.RIGHT)
+```
+
+### Dashboard
+
+```python
+from zbxtemplar.entities import Dashboard, DashboardPage
+from zbxtemplar.entities.DashboardWidget import ClassicGraph
+
+page = DashboardPage(name="Overview", display_period=120)
+page.add_widget(ClassicGraph(host=template.name, graph=graph, width=36, height=5))
+
+dashboard = Dashboard("My Dashboard", display_period=60, auto_start=YesNo.NO)
+dashboard.add_page(page)
+template.add_dashboard(dashboard)
+```
+
+Widgets are concrete subclasses of `Widget` (abstract). Each widget type lives in `zbxtemplar.entities.DashboardWidget`. Creating custom widgets is straightforward — subclass `Widget`, define `type` and `widget_fields()`.
+
+## Global Configuration
+
+```python
+from zbxtemplar.core.ZbxEntity import set_uuid_namespace, set_template_group
+
+set_uuid_namespace("My Company")    # Deterministic UUIDs scoped to namespace
+set_template_group("My Templates")  # Default group for new templates
+```

zbxtemplar-0.1.0/pyproject.toml

@@ -0,0 +1,34 @@
+[build-system]
+requires = ["setuptools>=61.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "zbxtemplar"
+version = "0.1.0"
+description = "Programmatic Zabbix template generation — Monitoring as Code"
+readme = "README.md"
+requires-python = ">=3.10"
+license = {file = "LICENSE"}
+authors = [
+  {name = "Aleksei Dorozhkin"}
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: System Administrators",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Topic :: System :: Monitoring",
+]
+dependencies = [
+    "pyyaml>=6.0",
+]
+
+[project.urls]
+"Homepage" = "https://github.com/mithraelle/zbxtemplar"
+"Bug Tracker" = "https://github.com/mithraelle/zbxtemplar/issues"
+
+[project.scripts]
+zbxtemplar = "zbxtemplar.main:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]

zbxtemplar-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

zbxtemplar-0.1.0/src/zbxtemplar/__main__.py

@@ -0,0 +1,3 @@
+from zbxtemplar.main import main
+
+raise SystemExit(main())

zbxtemplar-0.1.0/src/zbxtemplar/core/TemplarModule.py

@@ -0,0 +1,47 @@
+import inspect
+import importlib.util
+import os
+
+import zbxtemplar.core.ZbxEntity as _zbx
+
+
+class TemplarModule:
+    def __init__(self):
+        self.templates = []
+        self.triggers = []
+        self.graphs = []
+
+    def to_export(self, version: str = "7.4") -> dict:
+        groups = set()
+        for t in self.templates:
+            for g in t.groups:
+                groups.add(g["name"])
+
+        export = {
+            "zabbix_export": {
+                "version": version,
+                "template_groups": [
+                    {"uuid": _zbx._make_uuid(g), "name": g}
+                    for g in sorted(groups)
+                ],
+                "templates": [t.to_dict() for t in self.templates],
+            }
+        }
+        if self.triggers:
+            export["zabbix_export"]["triggers"] = [t.to_dict() for t in self.triggers]
+        if self.graphs:
+            export["zabbix_export"]["graphs"] = [g.to_dict() for g in self.graphs]
+        return export
+
+
+def load_module(filename: str) -> dict:
+    mod_name = os.path.splitext(os.path.basename(filename))[0]
+    spec = importlib.util.spec_from_file_location(mod_name, filename)
+    mod = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(mod)
+
+    result = {}
+    for name, obj in inspect.getmembers(mod, inspect.isclass):
+        if issubclass(obj, TemplarModule) and obj is not TemplarModule:
+            result[name] = obj()
+    return result

zbxtemplar-0.1.0/src/zbxtemplar/core/ZbxEntity.py

@@ -0,0 +1,165 @@
+from typing import Any, List, Optional, Dict, Union
+from enum import Enum
+import uuid
+
+class YesNo(str, Enum):
+    NO = "NO"
+    YES = "YES"
+
+ZBX_TEMPLAR_NAMESPACE = "Zbx Templar"
+ZBX_TEMPLAR_TEMPLATE_GROUP = "Templar Templates"
+_NAMESPACE_UUID = uuid.uuid5(uuid.NAMESPACE_DNS, ZBX_TEMPLAR_NAMESPACE)
+
+def set_uuid_namespace(namespace: str):
+    global ZBX_TEMPLAR_NAMESPACE, _NAMESPACE_UUID
+    ZBX_TEMPLAR_NAMESPACE = namespace
+    _NAMESPACE_UUID = uuid.uuid5(uuid.NAMESPACE_DNS, namespace)
+
+def set_template_group(group: str):
+    global ZBX_TEMPLAR_TEMPLATE_GROUP
+    ZBX_TEMPLAR_TEMPLATE_GROUP = group
+
+def _make_uuid(seed: str) -> str:
+    """Deterministic UUID from seed, masked as UUIDv4. Zabbix rejects UUID5 on import."""
+    h = uuid.uuid5(_NAMESPACE_UUID, seed).hex
+    return h[:12] + '4' + h[13:16] + hex(0x8 | (int(h[16], 16) & 0x3))[2:] + h[17:]
+
+def _serialize(value):
+    if hasattr(value, 'to_dict'):
+        return value.to_dict()
+    if isinstance(value, dict):
+        return {k: _serialize(v) for k, v in value.items()}
+    if isinstance(value, list):
+        return [_serialize(v) for v in value]
+    if isinstance(value, Enum):
+        return value.value
+    if hasattr(value, '__dict__') and not isinstance(value, (str, int, float, bool)):
+        return {k: _serialize(v) for k, v in value.__dict__.items()}
+    return value
+
+class ZbxEntity:
+    def __init__(self, name: str, uuid_seed: str = None):
+        super().__init__()
+        self.name = name
+        self.uuid = _make_uuid(uuid_seed or name)
+
+    def to_dict(self) -> dict[str, Any]:
+        # Attributes starting with _ are internal-only (e.g. _host) and skipped here
+        result = {}
+        for key, value in self.__dict__.items():
+            if key.startswith('_'):
+                continue
+            if value is None or value == {} or value == []:
+                continue
+            if key == 'tags' and hasattr(self, 'tags_to_list'):
+                result[key] = self.tags_to_list()
+            elif key == 'macros' and hasattr(self, 'macros_to_list'):
+                result[key] = self.macros_to_list()
+            else:
+                result[key] = _serialize(value)
+        return result
+
+class Tag:
+    def __init__(self, name: str, value: str = ""):
+        self.name = name
+        self.value = value
+
+    def to_dict(self):
+        return {"tag": self.name, "value": self.value}
+
+class WithTags():
+    def __init__(self):
+        super().__init__()
+        self.tags: Dict[str, Tag] = {}
+
+    def add_tag(self, tag: str, value: str = ""):
+        self.tags[tag] = Tag(name=tag, value=value)
+        return self
+
+    def tags_to_list(self):
+        return [t.to_dict() for t in self.tags.values()]
+
+    def load_tags(self, tags: Dict[str, str]):
+        """Load tags from a dict.
+
+        Args:
+            tags: Mapping of tag name to value.
+                Example: ``{"Application": "CPU", "Component": "OS"}``
+        """
+        for tag, value in tags.items():
+            self.add_tag(tag, value)
+        return self
+
+class Macro():
+    def __init__(self, name: str, value: str, description: Optional[str] = None):
+        self.name = name
+        self.value = value
+        self.description = description
+
+    @property
+    def full_name(self) -> str:
+        return f"{{${self.name}}}"
+
+    def __str__(self):
+        return self.full_name
+
+    def __add__(self, other):
+        return str(self) + other
+
+    def __radd__(self, other):
+        return other + str(self)
+
+    def to_dict(self):
+        result = {"macro": self.full_name, "value": self.value}
+        if self.description is not None:
+            result["description"] = self.description
+        return result
+
+class WithMacros():
+    def __init__(self):
+        super().__init__()
+        self.macros: Dict[str, Macro] = {}
+
+    def add_macro(self, name: str, value: Union[str, int], description: Union[str, None] = None):
+        clean_name = name.replace("{$", "").replace("}", "")
+        self.macros[clean_name] = Macro(name=clean_name, value=str(value), description=description)
+        return self
+
+    def load_macros(self, macros: Union[Dict[str, Union[str, tuple]], List[dict]]):
+        """Load macros from a dict or a list of dicts.
+
+        Accepts two formats:
+
+        **Dict** — for programmatic use::
+
+            load_macros({"TIMEOUT": "30"})
+            load_macros({"TIMEOUT": ("30", "Connection timeout")})
+
+        **List of dicts** — for data loaded from YAML/XML::
+
+            load_macros([
+                {"name": "TIMEOUT", "value": "30", "description": "Connection timeout"}
+            ])
+
+        Args:
+            macros: Either a ``{name: value}`` / ``{name: (value, description)}`` dict,
+                or a list of dicts with ``name``, ``value``, and optional ``description`` keys.
+        """
+        if isinstance(macros, dict):
+            for name, value in macros.items():
+                if isinstance(value, tuple):
+                    self.add_macro(name, value[0], value[1] if len(value) > 1 else None)
+                else:
+                    self.add_macro(name, value)
+        else:
+            for entry in macros:
+                self.add_macro(entry["name"], entry["value"], entry.get("description"))
+        return self
+
+    def macros_to_list(self):
+        return [m.to_dict() for m in self.macros.values()]
+
+    def get_macro(self, name: str) -> Optional[Macro]:
+        clean_name = name.replace("{$", "").replace("}", "")
+        return self.macros.get(clean_name)
+