a016db644d
- Changed references from "Oxi API" to "Oxidized API" for accuracy. - Added detailed installation instructions for using the Gitea Package Registry, including authentication steps and editable install options. - Improved clarity in the quick start section with formatted output examples.
304 lines
10 KiB
Markdown
304 lines
10 KiB
Markdown
# oxipy
|
||
|
||
Python-клиент для работы с Oxidized API — системой управления конфигурацией сетевых устройств. Предоставляет удобный интерфейс для получения конфигураций узлов, их парсинга и работы с результатами.
|
||
|
||
## Содержание
|
||
|
||
- [Установка](#установка)
|
||
- [Быстрый старт](#быстрый-старт)
|
||
- [API Reference](#api-reference)
|
||
- [OxiAPI](#oxiapi)
|
||
- [NodeView](#nodeview)
|
||
- [NodeConfig](#nodeconfig)
|
||
- [ModelView](#modelview)
|
||
- [Поддерживаемые устройства](#поддерживаемые-устройства)
|
||
- [Дополнительно](#дополнительно)
|
||
|
||
---
|
||
|
||
## Установка
|
||
|
||
> Пакет распространяется через Gitea Package Registry и исходники репозитория.
|
||
> В PyPI пакет не публикуется.
|
||
|
||
**Требования:** Python 3.13+
|
||
|
||
### Из 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-сертификат. `False` — отключить проверку |
|
||
|
||
**Пример:**
|
||
|
||
```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("Router_HOME")
|
||
print(node.ip)
|
||
```
|
||
|
||
#### `api.node(name)`
|
||
|
||
Возвращает [`NodeView`](#nodeview) для указанного узла.
|
||
|
||
```python
|
||
node = api.node("Router_HOME")
|
||
```
|
||
|
||
---
|
||
|
||
### NodeView
|
||
|
||
Представление узла сети. Содержит метаданные и ленивый доступ к конфигурации.
|
||
|
||
| Свойство | Тип | Описание |
|
||
|-------------|--------------|-----------------------------------------------|
|
||
| `ip` | `str` | IP-адрес узла |
|
||
| `full_name` | `str` | Полное имя узла в Oxi |
|
||
| `group` | `str` | Группа, к которой принадлежит узел |
|
||
| `model` | `str` | Модель устройства (используется для парсинга) |
|
||
| `config` | `NodeConfig` | Конфигурация узла (загружается при первом обращении) |
|
||
|
||
**Пример:**
|
||
|
||
```python
|
||
node = api.node("Router_HOME")
|
||
|
||
print(node.ip) # '10.0.0.1'
|
||
print(node.group) # 'branch-office'
|
||
print(node.model) # 'keenetic'
|
||
|
||
# Конфигурация загружается один раз (cached_property)
|
||
cfg = node.config
|
||
```
|
||
|
||
---
|
||
|
||
### 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) # 'RB951Ui-2nD'
|
||
print(cfg.system.serial_number) # 'B88C0B31117B'
|
||
print(cfg.system.version) # '7.12.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'
|
||
|
||
# Список — 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)
|