From b6630a4d301e9cf107e2a08bd5836a90634c4740 Mon Sep 17 00:00:00 2001 From: IluaAir Date: Wed, 25 Feb 2026 13:46:04 +0300 Subject: [PATCH] Update README for clarity and consistency - Simplified the description of the OxiAPI entry point. - Improved formatting of parameter and property tables for better readability. - Updated example outputs to reflect changes in node names and configurations. --- README.md | 110 ++++++++++++++++++++++++++++++++---------------------- 1 file changed, 65 insertions(+), 45 deletions(-) diff --git a/README.md b/README.md index 74c5bec..4dabb57 100644 --- a/README.md +++ b/README.md @@ -21,7 +21,7 @@ Python-клиент для работы с Oxidized API — системой у > Пакет распространяется через Gitea Package Registry и исходники репозитория. > В PyPI пакет не публикуется. -**Требования:** Python 3.13+ +**Требования:** Python 3.11+ ### Из Gitea Package Registry @@ -121,7 +121,7 @@ print(node.config.vlans.json()) ### OxiAPI -Точка входа в библиотеку. Управляет HTTP-сессией и предоставляет доступ к узлам. +Точка входа. Управляет HTTP-сессией и предоставляет доступ к узлам. ```python OxiAPI( @@ -132,12 +132,14 @@ OxiAPI( ) ``` -| Параметр | Тип | Описание | -|------------|--------|----------------------------------------------------------------| -| `url` | `str` | Базовый URL Oxi API, например `https://oxi.example.com` | -| `username` | `str` | Имя пользователя для базовой аутентификации (опционально) | -| `password` | `str` | Пароль для базовой аутентификации (опционально) | -| `verify` | `bool` | Проверять SSL-сертификат. `False` — отключить проверку | + +| Параметр | Тип | Описание | +| ---------- | ------ | --------------------------------------------------------- | +| `url` | `str` | Базовый URL Oxi API, например `https://oxi.example.com` | +| `username` | `str` | Имя пользователя для базовой аутентификации (опционально) | +| `password` | `str` | Пароль для базовой аутентификации (опционально) | +| `verify` | `bool` | Проверять SSL-сертификат. `True` по умолчанию | + **Пример:** @@ -154,16 +156,18 @@ api = OxiAPI( # Использование как контекстного менеджера (автоматически закрывает сессию) with OxiAPI(url="https://oxi.example.com") as api: - node = api.node("Router_HOME") + node = api.node("HQ") print(node.ip) + +>>> 192.168.1.1 ``` #### `api.node(name)` -Возвращает [`NodeView`](#nodeview) для указанного узла. +Возвращает `[NodeView](#nodeview)` для указанного узла. ```python -node = api.node("Router_HOME") +node = api.node("HQ") ``` --- @@ -172,25 +176,28 @@ node = api.node("Router_HOME") Представление узла сети. Содержит метаданные и ленивый доступ к конфигурации. -| Свойство | Тип | Описание | -|-------------|--------------|-----------------------------------------------| -| `ip` | `str` | IP-адрес узла | -| `full_name` | `str` | Полное имя узла в Oxi | -| `group` | `str` | Группа, к которой принадлежит узел | -| `model` | `str` | Модель устройства (используется для парсинга) | + +| Свойство | Тип | Описание | +| ----------- | ------------ | ---------------------------------------------------- | +| `ip` | `str` | IP-адрес узла | +| `full_name` | `str` | Полное имя узла в Oxi | +| `group` | `str` | Группа, к которой принадлежит узел | +| `model` | `str` | Модель устройства (используется для парсинга) | | `config` | `NodeConfig` | Конфигурация узла (загружается при первом обращении) | + **Пример:** ```python -node = api.node("Router_HOME") +node = api.node("HQ") -print(node.ip) # '10.0.0.1' -print(node.group) # 'branch-office' -print(node.model) # 'keenetic' +print(node.ip) +print(node.group) +print(node.model) -# Конфигурация загружается один раз (cached_property) -cfg = node.config +>>> 192.168.1.1 +>>> branch-office +>>> keenetic ``` --- @@ -199,14 +206,16 @@ cfg = node.config Загружает и парсит конфигурацию устройства. Использует TTP-шаблоны, соответствующие модели устройства. -Доступ к секциям конфигурации осуществляется через свойства, возвращающие [`ModelView`](#modelview). +Доступ к секциям конфигурации осуществляется через свойства, возвращающие `[ModelView](#modelview)`. + + +| Свойство | Возвращает | Описание | +| ------------ | ----------------------------- | ---------------------------------- | +| `system` | `ModelView[System]` | Системная информация об устройстве | +| `interfaces` | `ModelView[list[Interfaces]]` | Список интерфейсов | +| `vlans` | `ModelView[list[Vlans]]` | Список VLAN (если есть) | +| `text` | `str` | Сырой текст конфигурации | -| Свойство | Возвращает | Описание | -|--------------|-------------------------|-----------------------------------| -| `system` | `ModelView[System]` | Системная информация об устройстве | -| `interfaces` | `ModelView[list[Interfaces]]` | Список интерфейсов | -| `vlans` | `ModelView[list[Vlans]]` | Список VLAN (если есть) | -| `text` | `str` | Сырой текст конфигурации | **Пример:** @@ -214,9 +223,13 @@ cfg = node.config cfg = node.config # Системная информация -print(cfg.system.model) # 'RB951Ui-2nD' -print(cfg.system.serial_number) # 'B88C0B31117B' -print(cfg.system.version) # '7.12.1' +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: @@ -244,13 +257,15 @@ print(cfg.text) Обёртка над Pydantic-моделью или списком моделей. Обеспечивает сериализацию, итерацию и прозрачный доступ к атрибутам. -| Метод / свойство | Применимо к | Описание | -|------------------|----------------|---------------------------------------------------------------| -| `.json()` | оба варианта | Возвращает JSON-строку (с `by_alias=True`) | -| `.` | оба варианта | Проксирует обращение к атрибутам вложенной модели | -| `iter(view)` | список | Итерация по элементам списка моделей | -| `len(view)` | список | Количество элементов в списке | -| `view[i]` | список | Получение элемента по индексу или срез | + +| Метод / свойство | Применимо к | Описание | +| ---------------- | ------------ | ------------------------------------------------- | +| `.json()` | оба варианта | Возвращает JSON-строку (с `by_alias=True`) | +| `.` | оба варианта | Проксирует обращение к атрибутам вложенной модели | +| `iter(view)` | список | Итерация по элементам списка моделей | +| `len(view)` | список | Количество элементов в списке | +| `view[i]` | список | Получение элемента по индексу или срез | + > `__iter__`, `__len__` и `__getitem__` доступны только для `interfaces` и `vlans` (они оборачивают список). Вызов этих методов на `system` (одиночная модель) вызовет `TypeError`. @@ -260,10 +275,12 @@ print(cfg.text) # Одиночная модель — system view = node.config.system print(view.json()) -# '{"model":"RB951Ui-2nD","serial_number":"B88C0B31117B","version":"7.12.1"}' +>>> '{"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 @@ -286,10 +303,12 @@ print(interfaces.json()) ## Поддерживаемые устройства -| Устройство | Ключи реестра | -|-------------|----------------------------------------| -| Keenetic | `ndms`, `keenetic`, `keeneticos` | -| MikroTik | `routeros`, `ros`, `mikrotik` | + +| Устройство | Ключи реестра | +| ---------- | -------------------------------- | +| Keenetic | `ndms`, `keenetic`, `keeneticos` | +| MikroTik | `routeros`, `ros`, `mikrotik` | + Ключи реестра — это значения поля `model`, возвращаемого API для узла. Регистр не учитывается. @@ -301,3 +320,4 @@ print(interfaces.json()) - [Написание TTP-шаблонов](docs/templates.md) - [Расширение и переопределение моделей устройств](docs/extending-models.md) +