Netbox/oxipy
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Merge branch 'docs' into dev

Browse Source
This commit is contained in:
IluaAir
2026-02-25 22:42:51 +03:00
parent 2c3f5ce354 b6630a4d30
commit 9e4574e869
4 changed files with 997 additions and 1 deletions
Download Patch File Download Diff File Expand all files Collapse all files

323
README.md
View File

@@ -0,0 +1,323 @@
# oxipy
Python-клиент для работы с Oxidized API — системой управления конфигурацией сетевых устройств. Предоставляет удобный интерфейс для получения конфигураций узлов, их парсинга и работы с результатами.
## Содержание
- [Установка](#установка)
- [Быстрый старт](#быстрый-старт)
- [API Reference](#api-reference)
- [OxiAPI](#oxiapi)
- [NodeView](#nodeview)
- [NodeConfig](#nodeconfig)
- [ModelView](#modelview)
- [Поддерживаемые устройства](#поддерживаемые-устройства)
- [Дополнительно](#дополнительно)
---
## Установка
> Пакет распространяется через Gitea Package Registry и исходники репозитория.
> В PyPI пакет не публикуется.
**Требования:** Python 3.11+
### Из Gitea Package Registry
Добавьте registry в конфигурацию pip и установите пакет:
```bash
pip install oxipy \
--index-url https://gitea.imbastark.ru/api/packages/Netbox/pypi/simple/
```
Или пропишите registry постоянно в `pip.conf` / `pip.ini`, чтобы не указывать `--index-url` каждый раз:
```ini
# ~/.config/pip/pip.conf (Linux/macOS)
# %APPDATA%\pip\pip.ini (Windows)
[global]
extra-index-url = https://gitea.imbastark.ru/api/packages/Netbox/pypi/simple/
```
После этого достаточно:
```bash
pip install oxipy
```
Если registry требует аутентификации, передайте токен:
```bash
pip install oxipy \
--index-url https://__token__:<your_token>@gitea.imbastark.ru/api/packages/Netbox/pypi/simple/
```
### Из репозитория Gitea
Установка напрямую через pip без клонирования:
```bash
pip install git+https://gitea.imbastark.ru/Netbox/oxipy.git
```
Конкретный тег или ветка:
```bash
pip install git+https://gitea.imbastark.ru/Netbox/oxipy.git@v0.1.0
pip install git+https://gitea.imbastark.ru/Netbox/oxipy.git@dev
```
Для разработки (editable install):
```bash
git clone https://gitea.imbastark.ru/Netbox/oxipy
cd oxipy
pip install -e .
```
---
## Быстрый старт
```python
from oxi import OxiAPI
api = OxiAPI(url="https://oxi.example.com", verify=False)
node = api.node("Router_HOME")
print(node.ip)
print(node.model)
print(node.full_name)
>>> 192.168.1.1
>>> keenetic
>>> router/HQ
print(node.config.system.model)
print(node.config.interfaces.json())
print(node.config.vlans.json())
>>> Sprinter (KN-3710)
>>>
[
{"name":"Bridge1","ip_address":"192.168.1.1","mask":24,"description":"\"Guest network\""},
{"name":"Bridge0","ip_address":"172.16.1.1","mask":24,"description":"\"Home network\""}
]
>>>
[
{"vlan_id":1,"name":"Home VLAN"},
{"vlan_id":2,"name":"Подключение Ethernet"},
{"vlan_id":3,"name":"Home network"}
]
```
---
## API Reference
### OxiAPI
Точка входа. Управляет HTTP-сессией и предоставляет доступ к узлам.
```python
OxiAPI(
url: str,
username: str | None = None,
password: str | None = None,
verify: bool = True,
)
```
| Параметр | Тип | Описание |
| ---------- | ------ | --------------------------------------------------------- |
| `url` | `str` | Базовый URL Oxi API, например `https://oxi.example.com` |
| `username` | `str` | Имя пользователя для базовой аутентификации (опционально) |
| `password` | `str` | Пароль для базовой аутентификации (опционально) |
| `verify` | `bool` | Проверять SSL-сертификат. `True` по умолчанию |
**Пример:**
```python
# Без аутентификации
api = OxiAPI(url="https://oxi.example.com")
# С базовой аутентификацией
api = OxiAPI(
url="https://oxi.example.com",
username="admin",
password="secret",
)
# Использование как контекстного менеджера (автоматически закрывает сессию)
with OxiAPI(url="https://oxi.example.com") as api:
node = api.node("HQ")
print(node.ip)
>>> 192.168.1.1
```
#### `api.node(name)`
Возвращает `[NodeView](#nodeview)` для указанного узла.
```python
node = api.node("HQ")
```
---
### NodeView
Представление узла сети. Содержит метаданные и ленивый доступ к конфигурации.
| Свойство | Тип | Описание |
| ----------- | ------------ | ---------------------------------------------------- |
| `ip` | `str` | IP-адрес узла |
| `full_name` | `str` | Полное имя узла в Oxi |
| `group` | `str` | Группа, к которой принадлежит узел |
| `model` | `str` | Модель устройства (используется для парсинга) |
| `config` | `NodeConfig` | Конфигурация узла (загружается при первом обращении) |
**Пример:**
```python
node = api.node("HQ")
print(node.ip)
print(node.group)
print(node.model)
>>> 192.168.1.1
>>> branch-office
>>> keenetic
```
---
### NodeConfig
Загружает и парсит конфигурацию устройства. Использует TTP-шаблоны, соответствующие модели устройства.
Доступ к секциям конфигурации осуществляется через свойства, возвращающие `[ModelView](#modelview)`.
| Свойство | Возвращает | Описание |
| ------------ | ----------------------------- | ---------------------------------- |
| `system` | `ModelView[System]` | Системная информация об устройстве |
| `interfaces` | `ModelView[list[Interfaces]]` | Список интерфейсов |
| `vlans` | `ModelView[list[Vlans]]` | Список VLAN (если есть) |
| `text` | `str` | Сырой текст конфигурации |
**Пример:**
```python
cfg = node.config
# Системная информация
print(cfg.system.model)
print(cfg.system.serial_number)
print(cfg.system.version)
>>> Mikrotik RB951Ui-2nD
>>> B88C0B31117B
>>> 7.16.1
# Итерация по интерфейсам
for iface in cfg.interfaces:
print(iface.name, iface.ip_address, iface.mask)
# Индексация
first_iface = cfg.interfaces[0]
print(first_iface.name)
# Количество интерфейсов
print(len(cfg.interfaces))
# JSON-дамп любой секции
print(cfg.interfaces.json())
print(cfg.vlans.json())
print(cfg.system.json())
# Сырая конфигурация текстом
print(cfg.text)
```
---
### ModelView
Обёртка над Pydantic-моделью или списком моделей. Обеспечивает сериализацию, итерацию и прозрачный доступ к атрибутам.
| Метод / свойство | Применимо к | Описание |
| ---------------- | ------------ | ------------------------------------------------- |
| `.json()` | оба варианта | Возвращает JSON-строку (с `by_alias=True`) |
| `.<attr>` | оба варианта | Проксирует обращение к атрибутам вложенной модели |
| `iter(view)` | список | Итерация по элементам списка моделей |
| `len(view)` | список | Количество элементов в списке |
| `view[i]` | список | Получение элемента по индексу или срез |
> `__iter__`, `__len__` и `__getitem__` доступны только для `interfaces` и `vlans` (они оборачивают список). Вызов этих методов на `system` (одиночная модель) вызовет `TypeError`.
**Примеры:**
```python
# Одиночная модель — system
view = node.config.system
print(view.json())
>>> '{"model":"RB951Ui-2nD","serial_number":"B88C0B31117B","version":"7.12.1"}'
print(view.model) # 'RB951Ui-2nD'
print(view.serial_number) # 'B88C0B31117B'
>>> RB951Ui-2nD
>>> B88C0B31117B
# Список — interfaces
interfaces = node.config.interfaces
# Итерация
for iface in interfaces:
print(iface.name, iface.ip_address)
# Длина
print(len(interfaces)) # 5
# Индексация и срезы
first = interfaces[0]
top3 = interfaces[:3]
# JSON всего списка
print(interfaces.json())
```
---
## Поддерживаемые устройства
| Устройство | Ключи реестра |
| ---------- | -------------------------------- |
| Keenetic | `ndms`, `keenetic`, `keeneticos` |
| MikroTik | `routeros`, `ros`, `mikrotik` |
Ключи реестра — это значения поля `model`, возвращаемого API для узла. Регистр не учитывается.
Добавить поддержку нового устройства можно самостоятельно — подробнее в разделе [Расширение моделей](docs/extending-models.md).
---
## Дополнительно
- [Написание TTP-шаблонов](docs/templates.md)
- [Расширение и переопределение моделей устройств](docs/extending-models.md)

325
docs/extending-models.md Normal file
View File

@@ -0,0 +1,325 @@
# Расширение и переопределение моделей устройств
oxipy предоставляет гибкий механизм расширения через наследование от `BaseDevice`. После того как TTP-шаблон разобрал конфигурацию в сырой словарь `self.raw`, данные проходят через три метода экземпляра — `system()`, `interfaces()`, `vlans()` — перед тем как попасть в контракт. Переопределяя эти методы, можно трансформировать, фильтровать и обогащать данные без изменения шаблона или контракта.
## Содержание
- [Архитектура: путь данных](#архитектура-путь-данных)
- [Регистрация нового устройства](#регистрация-нового-устройства)
- [Переопределение методов (monkey patching)](#переопределение-методов-monkey-patching)
- [interfaces()](#interfaces)
- [vlans()](#vlans)
- [system()](#system)
- [Полный пример: новое устройство](#полный-пример-новое-устройство)
- [Контракт: ожидаемые структуры](#контракт-ожидаемые-структуры)
---
## Архитектура: путь данных
```
текст конфигурации
│
▼
TTP-шаблон (.ttp)
│ парсит в сырой словарь
▼
self.raw: dict
│
├──► system() → dict
├──► interfaces() → list[dict]
└──► vlans() → list[dict]
│
▼
_validate_contract()
│ создаёт Pydantic-модели
▼
Device(system, interfaces, vlans)
```
Методы `system()`, `interfaces()`, `vlans()` — это точки расширения. Базовая реализация просто возвращает данные из `self.raw`:
```python
# BaseDevice (упрощённо)
def interfaces(self) -> list[dict]:
return self.raw.get("interfaces", [])
def vlans(self) -> list[dict]:
return self.raw.get("vlans", [])
def system(self) -> dict:
return self.raw.get("system", None)
```
---
## Регистрация нового устройства
Чтобы добавить поддержку нового вендора:
1. Создайте файл в `oxi/interfaces/models/`, например `cisco.py`.
2. Создайте шаблон `oxi/interfaces/models/templates/cisco.ttp`.
3. Унаследуйте класс от `BaseDevice` и зарегистрируйте его декоратором `@register_parser`.
```python
# oxi/interfaces/models/cisco.py
from oxi.interfaces import register_parser
from oxi.interfaces.base import BaseDevice
@register_parser(["ios", "cisco", "cisco_ios"])
class CiscoIOS(BaseDevice):
template = "cisco.ttp"
```
Декоратор `@register_parser` принимает список строк — это ключи, по которым устройство ищется в реестре. Поле `model` от API сравнивается с этими ключами без учёта регистра.
После добавления файла он автоматически импортируется через `pkgutil` при старте приложения — явно импортировать не нужно.
---
## Переопределение методов (monkey patching)
### interfaces()
Используйте переопределение, когда нужно:
- Преобразовать формат IP-адреса (например, `netmask` → `prefix_length`).
- Декодировать escape-последовательности в описаниях.
- Переименовать ключи, не совпадающие с контрактом.
- Фильтровать служебные интерфейсы.
**Пример: конвертация маски подсети в префикс**
TTP возвращает `netmask` как `255.255.255.0`, а контракт `Interfaces` ожидает `mask` как целое число (prefix length):
```python
from ipaddress import ip_interface
from oxi.interfaces import register_parser
from oxi.interfaces.base import BaseDevice
@register_parser(["myvendor"])
class MyVendor(BaseDevice):
template = "myvendor.ttp"
def interfaces(self) -> list[dict]:
result = []
for item in self.raw.get("interfaces", []):
if item.get("ip_address") and item.get("netmask"):
iface = ip_interface(f"{item['ip_address']}/{item['netmask']}")
item["mask"] = iface.network.prefixlen
item.pop("netmask", None)
result.append(item)
return result
```
**Пример: фильтрация служебных интерфейсов**
```python
def interfaces(self) -> list[dict]:
return [
item for item in self.raw.get("interfaces", [])
if not item.get("name", "").startswith("lo")
]
```
**Пример: декодирование Unicode escape-последовательностей**
Некоторые устройства (например, Keenetic) хранят кириллические описания как `\xd0\xb8\xd0\xbc\xd1\x8f`:
```python
def _decode_utf(self, text: str) -> str:
if "\\x" in text:
return (
text.strip('"')
.encode("utf-8")
.decode("unicode_escape")
.encode("latin1")
.decode("utf-8")
)
return text
def interfaces(self) -> list[dict]:
interfaces = self.raw.get("interfaces", [])
for item in interfaces:
if item.get("description"):
item["description"] = self._decode_utf(item["description"])
return interfaces
```
---
### vlans()
Аналогично `interfaces()`. Используйте для нормализации ID, декодирования названий, обогащения данными из других секций.
**Пример: добавление префикса к имени VLAN**
```python
def vlans(self) -> list[dict]:
result = []
for item in self.raw.get("vlans", []):
item["description"] = f"VLAN_{item.get('id', '?')}"
result.append(item)
return result
```
**Пример: объединение данных из нескольких секций**
```python
def vlans(self) -> list[dict]:
vlans = {v["id"]: v for v in self.raw.get("vlans", [])}
# обогащаем данными из другой секции, если она есть
for extra in self.raw.get("vlan_details", []):
vlan_id = extra.get("id")
if vlan_id in vlans:
vlans[vlan_id].update(extra)
return list(vlans.values())
```
---
### system()
Переопределяйте, если структура системной секции отличается от ожидаемой контрактом, или нужно вычислить поля:
**Пример: собрать серийный номер из нескольких полей**
```python
def system(self) -> dict:
raw_system = self.raw.get("system", {})
# Устройство возвращает серийный номер в двух частях
part1 = raw_system.get("serial_part1", "")
part2 = raw_system.get("serial_part2", "")
raw_system["serial_number"] = f"{part1}-{part2}"
return raw_system
```
**Пример: нормализация строки версии**
```python
def system(self) -> dict:
raw_system = self.raw.get("system", {})
# Убираем лишнее из "7.12.1 (stable)" → "7.12.1"
version = raw_system.get("version", "")
raw_system["version"] = version.split()[0] if version else version
return raw_system
```
---
## Полный пример: новое устройство
Допустим, нужно добавить поддержку Cisco IOS, где:
- IP-адрес и маска разделены пробелом в конфигурации (`ip address 10.0.0.1 255.255.255.0`).
- Описание интерфейса может содержать несколько слов.
- Серийный номер разделён дефисом в двух строках.
**Шаблон** (`oxi/interfaces/models/templates/cisco.ttp`):
```xml
<vars>
default_system = {
"model": "",
"serial_number": "",
"version": ""
}
</vars>
<group name="system" default="default_system">
Cisco IOS Software, {{ ignore }} Version {{ version }},{{ ignore('.*') }}
Model Number : {{ model }}
System serial number : {{ serial_number }}
</group>
<group name="interfaces">
interface {{ interface | _start_ }}
description {{ description | ORPHRASE }}
ip address {{ ip_address }} {{ netmask }}
</group>
<group name="vlans">
vlan {{ id | _start_ }}
name {{ description }}
</group>
```
**Класс устройства** (`oxi/interfaces/models/cisco.py`):
```python
from ipaddress import ip_interface
from oxi.interfaces import register_parser
from oxi.interfaces.base import BaseDevice
@register_parser(["ios", "cisco", "cisco_ios"])
class CiscoIOS(BaseDevice):
template = "cisco.ttp"
def interfaces(self) -> list[dict]:
result = []
for item in self.raw.get("interfaces", []):
# Конвертируем маску подсети в длину префикса
if item.get("ip_address") and item.get("netmask"):
iface = ip_interface(f"{item['ip_address']}/{item['netmask']}")
item["mask"] = iface.network.prefixlen
item.pop("netmask", None)
# Фильтруем интерфейсы управления
if item.get("interface", "").startswith("Mgmt"):
continue
result.append(item)
return result
def system(self) -> dict:
raw_system = self.raw.get("system", {})
# Нормализуем версию: "15.2(4)M3" → оставляем как есть
# Убираем лишние пробелы в модели
if raw_system.get("model"):
raw_system["model"] = raw_system["model"].strip()
return raw_system
```
---
## Контракт: ожидаемые структуры
Методы должны возвращать данные в следующем формате. Контракт жёстко проверяется Pydantic.
### `system()` → `dict`
```python
{
"model": "RB951Ui-2nD", # str, обязательно
"serial_number": "B88C0B31117B", # str, обязательно
"version": "7.12.1", # str, обязательно
}
```
### `interfaces()` → `list[dict]`
```python
[
{
"interface": "ether1", # str, обязательно (alias для поля name)
"ip_address": "192.168.1.1", # str | None
"mask": 24, # int | None (длина префикса)
"description": "LAN", # str | None
},
...
]
```
### `vlans()` → `list[dict]`
```python
[
{
"id": 10, # int, обязательно (alias для поля vlan_id)
"description": "MGMT", # str | None (alias для поля name)
},
...
]
```
> Если имя ключа в словаре совпадает с **alias** поля Pydantic-модели, а не с именем атрибута — используйте alias. Модели сконфигурированы с `populate_by_name=True`, поэтому принимаются оба варианта.

306
docs/templates.md Normal file
View File

@@ -0,0 +1,306 @@
# Написание TTP-шаблонов
oxipy использует библиотеку [TTP (Template Text Parser)](https://ttp.readthedocs.io/) для парсинга конфигураций сетевых устройств в структурированные данные. Шаблоны хранятся в директории `oxi/interfaces/models/templates/`.
## Содержание
- [Структура шаблона](#структура-шаблона)
- [Обязательные группы](#обязательные-группы)
- [Секция system](#секция-system)
- [Секция interfaces](#секция-interfaces)
- [Секция vlans](#секция-vlans)
- [TTP: основные возможности](#ttp-основные-возможности)
- [Переменные по умолчанию](#переменные-по-умолчанию)
- [Практические примеры](#практические-примеры)
- [Валидация шаблона](#валидация-шаблона)
---
## Структура шаблона
Каждый шаблон — это `.ttp`-файл, состоящий из следующих блоков:
```xml
<doc>
Описание шаблона (опционально)
</doc>
<vars>
<!-- Переменные по умолчанию для групп -->
</vars>
<group name="system">
<!-- Правила для системной информации -->
</group>
<group name="interfaces">
<!-- Правила для интерфейсов -->
</group>
<group name="vlans">
<!-- Правила для VLAN (опционально) -->
</group>
```
Файл-заготовка находится в `oxi/interfaces/models/templates/_template.ttp`.
---
## Обязательные группы
Фреймворк требует наличия в шаблоне **двух обязательных групп**:
| Группа | Обязательна | Описание |
|--------------|-------------|-------------------------------|
| `system` | Да | Системная информация |
| `interfaces` | Да | Конфигурация интерфейсов |
| `vlans` | Нет | Конфигурация VLAN |
Если обязательная группа отсутствует в шаблоне или TTP не вернул её данные, будет выброшено `ValueError`.
---
## Секция system
Должна возвращать словарь со следующими полями:
| Поле | Тип | Обязательное | Описание |
|-----------------|------|--------------|---------------------|
| `model` | str | Да | Модель устройства |
| `serial_number` | str | Да | Серийный номер |
| `version` | str | Да | Версия прошивки |
**Пример (MikroTik):**
Конфигурация:
```
# version: 7.12.1 (stable)
# model = RB951Ui-2nD
# serial number = B88C0B31117B
```
Шаблон:
```
<group name="system">
# version: {{ version }}{{ ignore('.*') }}
# model = {{ model }}
# serial number = {{ serial_number }}
</group>
```
**Пример (Keenetic):**
Конфигурация:
```
! release: 4.1.7.1-1
! model: Keenetic Extra
! hw_version: F02B4E7A1C90
```
Шаблон:
```
<group name="system">
! release: {{ version }}
! model: {{ model | ORPHRASE }}
! hw_version: {{ serial_number }}
</group>
```
---
## Секция interfaces
Должна возвращать список словарей. Каждый словарь описывает один интерфейс.
Поля, которые ожидает контракт `Interfaces`:
| Поле | TTP-имя / alias | Тип | Обязательное |
|---------------|-----------------|------------------|--------------|
| `name` | `interface` | str | Да |
| `ip_address` | `ip_address` | IPv4Address | Нет |
| `mask` | `mask` | int (prefix len) | Нет |
| `description` | `description` | str | Нет |
> **Важно:** поле `name` в Pydantic-модели имеет алиас `interface`, поэтому в шаблоне переменную нужно называть именно `interface` **или** переопределить метод `interfaces()` в классе модели (см. [Расширение моделей](extending-models.md)).
**Пример (MikroTik):**
Конфигурация:
```
/ip address
add address=192.168.1.1/24 interface=ether1 network=192.168.1.0
add address=10.0.0.1/30 comment="WAN link" interface=ether2 network=10.0.0.0
```
Шаблон:
```
<group name="interfaces">
/ip address
add address={{ ip_address | _start_ }}/{{ mask }} interface={{ interface }} network={{ network }}
add address={{ ip_address | _start_ }}/{{ mask }} comment={{ description | ORPHRASE | strip('"') }} interface={{ interface }} network={{ network }}
</group>
```
**Пример (Keenetic):**
Конфигурация:
```
interface GigabitEthernet0/0
description "WAN"
ip address 10.0.0.2 255.255.255.252
interface GigabitEthernet0/1
ip address 192.168.1.1 255.255.255.0
```
Шаблон:
```
<group name="interfaces">
interface {{ name | _start_ | exclude("Vlan") }}
description {{ description | ORPHRASE }}
ip address {{ ip_address }} {{ netmask }}
</group>
```
Здесь переменная называется `name`, а не `interface` — это покрывается переопределением метода `interfaces()` в классе `Keenetic`.
---
## Секция vlans
Необязательная группа. Если объявлена в шаблоне, фреймворк ожидает её наличия в результате TTP.
Поля контракта `Vlans`:
| Поле | TTP-имя / alias | Тип | Обязательное |
|-----------|-----------------|------|--------------|
| `vlan_id` | `id` | int | Да |
| `name` | `description` | str | Нет |
> `vlan_id` имеет алиас `id`, поэтому в шаблоне переменная должна называться `id` либо переименовываться в методе `vlans()`.
**Пример (Keenetic):**
Конфигурация:
```
interface Bridge0/Vlan10
description "MGMT"
interface Bridge0/Vlan20
description "SERVERS"
```
Шаблон:
```
<group name="vlans">
interface {{ ignore }}/Vlan{{ id }}
description {{ description | ORPHRASE | strip('"') }}
</group>
```
---
## TTP: основные возможности
### Маркеры строк
| Маркер | Описание |
|-------------|---------------------------------------------------------------|
| `_start_` | Строка с этой переменной считается началом нового совпадения |
| `_end_` | Строка с этой переменной завершает совпадение группы |
```
add address={{ ip_address | _start_ }}/{{ mask }} interface={{ name }}
```
### Модификаторы переменных
| Модификатор | Описание |
|------------------------|-----------------------------------------------------------|
| `ORPHRASE` | Захватывает одно слово или фразу (до конца строки) |
| `exclude("pattern")` | Пропускает строку, если захваченное значение содержит паттерн |
| `strip('"')` | Удаляет символ из начала и конца захваченного значения |
| `replace("old","new")` | Заменяет подстроку в захваченном значении |
| `re("pattern")` | Принимает значение, только если оно соответствует regex |
| `ignore` | Захватывает, но игнорирует значение (не включает в результат) |
| `ignore('.*')` | Игнорирует всё до конца строки |
### Комментарии в шаблоне
Строки, начинающиеся с `##`, — это комментарии TTP и не влияют на парсинг:
```
## disabled no comment
add address={{ ip_address | _start_ }}/{{ mask }} interface={{ name }}
```
---
## Переменные по умолчанию
Блок `<vars>` позволяет задавать значения по умолчанию для группы через атрибут `default`:
```xml
<vars>
default_system = {
"model": "",
"serial_number": ""
}
</vars>
<group name="system" default="default_system">
# version: {{ version }}
# model = {{ model }}
# serial number = {{ serial_number }}
</group>
```
Если шаблон не нашёл совпадений для группы, будет возвращён словарь из `default_system`.
---
## Практические примеры
### Полный шаблон для нового устройства (пример: Cisco IOS)
```xml
<doc>
Шаблон для парсинга Cisco IOS running-config
</doc>
<vars>
default_system = {
"model": "",
"serial_number": "",
"version": ""
}
</vars>
<group name="system" default="default_system">
Cisco IOS Software, {{ ignore }} Version {{ version }},{{ ignore('.*') }}
Model Number : {{ model }}
System serial number : {{ serial_number }}
</group>
<group name="interfaces">
interface {{ interface | _start_ }}
description {{ description | ORPHRASE }}
ip address {{ ip_address }} {{ netmask }}
shutdown {{ shutdown | set("True") }}
</group>
<group name="vlans">
vlan {{ id | _start_ }}
name {{ description }}
</group>
```
---
## Валидация шаблона
Фреймворк автоматически выполняет два уровня проверки:
1. **Валидация структуры шаблона** — при создании объекта устройства парсятся XML-теги `<group>` и проверяется наличие обязательных секций (`system`, `interfaces`).
2. **Валидация результата парсинга** — после запуска TTP проверяется, что обязательные группы действительно присутствуют в результате (т.е. конфигурация содержала соответствующие строки).
При нарушении любого условия выбрасывается `ValueError` с подробным описанием проблемы.

44
oxi/interfaces/models/templates/_template.ttp
View File

@@ -1,9 +1,51 @@
<doc> <doc>
Базовый шаблон для нового устройства. Скопируйте этот файл, переименуйте
в <vendor>.ttp и заполните группы под формат конфигурации вашего устройства.
Обязательные группы: system, interfaces.
Опциональная группа: vlans — добавляйте только если устройство поддерживает VLAN.
--- Группа system ---
Должна возвращать одиночный словарь с полями:
model (str) — модель устройства
serial_number (str) — серийный номер
version (str) — версия прошивки
--- Группа interfaces ---
Должна возвращать список словарей. Каждый элемент:
interface (str) — имя интерфейса (alias поля name)
ip_address (str|None) — IPv4-адрес
mask (int|None) — длина префикса (напр. 24)
description (str|None) — описание интерфейса
Если устройство возвращает маску в виде 255.255.255.0, конвертируйте
её в prefix length в методе interfaces() класса устройства.
--- Группа vlans ---
Должна возвращать список словарей. Каждый элемент:
id (int) — номер VLAN (alias поля vlan_id)
description (str|None) — название VLAN (alias поля name)
--- Полезные модификаторы TTP ---
{{ field | ORPHRASE }} — одно слово или фраза до конца строки
{{ field | _start_ }} — начало новой записи группы
{{ field | strip('"') }} — убрать кавычки
{{ field | replace("yes","True") }} — замена подстроки
{{ field | exclude("pattern") }} — пропустить строку при совпадении
{{ ignore }} — захватить и выбросить значение
{{ ignore('.*') }} — выбросить всё до конца строки
Подробнее: docs/templates.md
</doc> </doc>
<vars> <vars>
default_system = {
"model": "",
"serial_number": "",
"version": ""
}
</vars> </vars>
<group name="system"> <group name="system" default="default_system">
... ...
</group> </group>