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.
This commit is contained in:
IluaAir
64
README.md
64
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` — отключить проверку |
|
||||
| `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` | Модель устройства (используется для парсинга) |
|
||||
| `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,24 +206,30 @@ cfg = node.config
|
||||
|
||||
Загружает и парсит конфигурацию устройства. Использует TTP-шаблоны, соответствующие модели устройства.
|
||||
|
||||
Доступ к секциям конфигурации осуществляется через свойства, возвращающие [`ModelView`](#modelview).
|
||||
Доступ к секциям конфигурации осуществляется через свойства, возвращающие `[ModelView](#modelview)`.
|
||||
|
||||
|
||||
| Свойство | Возвращает | Описание |
|
||||
|--------------|-------------------------|-----------------------------------|
|
||||
| ------------ | ----------------------------- | ---------------------------------- |
|
||||
| `system` | `ModelView[System]` | Системная информация об устройстве |
|
||||
| `interfaces` | `ModelView[list[Interfaces]]` | Список интерфейсов |
|
||||
| `vlans` | `ModelView[list[Vlans]]` | Список VLAN (если есть) |
|
||||
| `text` | `str` | Сырой текст конфигурации |
|
||||
|
||||
|
||||
**Пример:**
|
||||
|
||||
```python
|
||||
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,14 +257,16 @@ print(cfg.text)
|
||||
|
||||
Обёртка над Pydantic-моделью или списком моделей. Обеспечивает сериализацию, итерацию и прозрачный доступ к атрибутам.
|
||||
|
||||
|
||||
| Метод / свойство | Применимо к | Описание |
|
||||
|------------------|----------------|---------------------------------------------------------------|
|
||||
| ---------------- | ------------ | ------------------------------------------------- |
|
||||
| `.json()` | оба варианта | Возвращает JSON-строку (с `by_alias=True`) |
|
||||
| `.<attr>` | оба варианта | Проксирует обращение к атрибутам вложенной модели |
|
||||
| `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,11 +303,13 @@ print(interfaces.json())
|
||||
|
||||
## Поддерживаемые устройства
|
||||
|
||||
|
||||
| Устройство | Ключи реестра |
|
||||
|-------------|----------------------------------------|
|
||||
| ---------- | -------------------------------- |
|
||||
| Keenetic | `ndms`, `keenetic`, `keeneticos` |
|
||||
| MikroTik | `routeros`, `ros`, `mikrotik` |
|
||||
|
||||
|
||||
Ключи реестра — это значения поля `model`, возвращаемого API для узла. Регистр не учитывается.
|
||||
|
||||
Добавить поддержку нового устройства можно самостоятельно — подробнее в разделе [Расширение моделей](docs/extending-models.md).
|
||||
@@ -301,3 +320,4 @@ print(interfaces.json())
|
||||
|
||||
- [Написание TTP-шаблонов](docs/templates.md)
|
||||
- [Расширение и переопределение моделей устройств](docs/extending-models.md)
|
||||
|
||||
|
||||
Reference in New Issue
Block a user