Metadata-Version: 2.4
Name: ones-pyapi
Version: 0.1.2
Summary: Python SDK for ONES (Aviz Networks)
Author-email: Kavyansh Pandey <kavyansh.pandey@aviznetworks.com>
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: requests

# ones_pyapi

[![PyPI version](https://badge.fury.io/py/ones_pyapi.svg)](https://badge.fury.io/py/ones_pyapi)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

A modern, easy-to-use Python SDK for interacting with the ONES API. Designed for clarity, extensibility, and robust error handling.

---

## Features

- Simple and intuitive API client for Datacenter NetOps
- Supports Day 1 (provisioning) and Day 2 (lifecycle) operations for SONiC-based switches
- Organized resources for users, health, inventory, BGP, control plane, and more
- Custom exception handling for robust error management
- Comprehensive test suite and example usage scripts
- Designed for extensibility and clarity in modern Python projects

---

## Installation

```bash
pip install ones_pyapi
```

---

## Quick Start

```python
from ones.client import OnesClient

client = OnesClient(api_key="YOUR_API_KEY")

# Get user info
user = client.user.get(user_id="12345")
print(user)

# Check API health
health = client.health.status()
print(health)

# List inventory items
items = client.inventory.list()
for item in items:
    print(item)
```

---

## Project Structure

```
ones_sdk/
│
├── ones/                     # main package
│   ├── client.py             # main entry point
│   ├── transport.py          # HTTP layer
│   ├── exceptions.py         # custom errors
│   ├── constants.py          # endpoints, paths
│   ├── resources/            # API groups
│   │   ├── user.py
│   │   ├── health.py
│   │   └── inventory.py
│   ├── utils/                # helpers
│   │   └── parser.py
│   └── models/               # (optional, later)
│       └── user.py
│
├── tests/                    # test suite
├── examples/                 # usage examples
├── requirements.txt
├── setup.py / pyproject.toml
└── README.md
```

---

## API Reference

### `OnesClient`

#### Initialization

```python
client = OnesClient(api_key="YOUR_API_KEY")
```

#### User API

```python
client.user.get(user_id)
client.user.create(data)
client.user.update(user_id, data)
client.user.delete(user_id)
```

#### Health API

```python
client.health.status()
```

#### Inventory API

```python
client.inventory.list()
client.inventory.get(item_id)
client.inventory.create(data)
client.inventory.update(item_id, data)
client.inventory.delete(item_id)
```

---

## Examples

See [`examples/basic_usage.py`](examples/basic_usage.py) for more.

---

## Testing

```bash
pytest tests/
```

---

## Contributing

Pull requests are welcome! For major changes, please open an issue first to discuss what you would like to change.

---

## License

This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.

---

## Links

- [PyPI Package](https://pypi.org/project/ones_pyapi/)
- [GitHub Repository](https://github.com/AvizNetworks/ones-pyapi)


# Usage
# examples/basic_usage.py
```python
# examples/basic_usage.py
```

## Basic Client Setup

All examples below use the following client initialization:

```python
from ones.client import ONESClient

client = ONESClient(
    url="https://your-instance/",
    username="your_username",
    password="your_password"
)

client.connect()
```

---

## User API

```python
# List all users
print(client.user.list())
```

---

## BGP API

> **BGP (Border Gateway Protocol)** is the routing protocol used to exchange routing information between network devices (e.g., SONiC switches). These APIs provide visibility into BGP sessions, neighbors, and telemetry data.

```python
# BGP List
bgp_list = client.bgp.bgp_list()
print("BGP List:", bgp_list)

# Neighbor List
neighbors = client.bgp.neighbor_list(device_address="xx:xx:xx:xx:xx:xx", vrf="default")
print("Neighbor List:", neighbors)

# Protocol Mega — aggregated BGP protocol telemetry over a time window
protocol_mega = client.bgp.protocol_mega(
    from_date="2026-03-23 10:09:36",
    to_date="2026-03-23 11:09:36",
    window_size="1 hour",
    device_address="xx:xx:xx:xx:xx:xx",
    vrf="default"
)
print("Protocol Mega:", protocol_mega)

# Protocol Neighbor Mega — aggregated BGP neighbor telemetry over a time window
protocol_neighbor_mega = client.bgp.protocol_neighbor_mega(
    from_date="2026-03-23 10:09:36",
    to_date="2026-03-23 11:09:36",
    window_size="1 hour",
    device_address="xx:xx:xx:xx:xx:xx",
    vrf="default"
)
print("Protocol Neighbor Mega:", protocol_neighbor_mega)

# BGP protocols for a specific IP
protocol_bgps = client.bgp.protocols_bgp(ip_address="x.x.x.x")
print("Protocol Map:", protocol_bgps)

# VLAN to BGP mapping
vlan_mapping = client.bgp.vlan_mapping(device_address="xx:xx:xx:xx:xx:xx")
print("VLAN Mapping:", vlan_mapping)
```

---

## Control Plane API

> **Control Plane** refers to the part of a network switch (such as SONiC) responsible for signaling, routing decisions, and protocol management. These APIs expose key control plane features:
> - **VLAN** – Virtual LAN segmentation
> - **MCLAG** – Multi-Chassis Link Aggregation Group for redundancy
> - **LACP** – Link Aggregation Control Protocol for bonding ports
> - **VRRP** – Virtual Router Redundancy Protocol for gateway failover

```python
# VLAN
vlan_info = client.control_plane.vlan()
print("VLAN Info:", vlan_info)

# MCLAG
mclag_info = client.control_plane.mclag()
print("MCLAG Info:", mclag_info)

# LACP
lacp_info = client.control_plane.lacp()
print("LACP Info:", lacp_info)

# VRRP
vrrp_info = client.control_plane.vrrp()
print("VRRP Info:", vrrp_info)
```

---

## Fabric Manager (FM) API

> **Day 1 Operations** refer to the initial provisioning and configuration of network devices — defining intents, validating configurations, and deploying them to SONiC switches for the first time.
>
> **Day 2 Operations** refer to ongoing lifecycle management after initial deployment — such as backing up configs, restoring previous states, applying patches, and monitoring config drift.

```python
# --- Day 1: Fabric & Intent Management ---

# List all fabrics
fabrics = client.fm.listFabric()
print("Fabrics:", fabrics)

# Upload an intent (Day 1 — initial desired state definition)
client.fm.uploadIntent({"fabricId": "fab1", "intent": "..."})

# Validate the uploaded intent before applying
client.fm.validateIntent({"fabricId": "fab1"})

# Check validation results
validation = client.fm.getIntentValidation(fabricId="fab1")
print("Validation:", validation)

# Apply the intent to provision the fabric
client.fm.applyIntent({"fabricId": "fab1"})

# Check provisioning status
status = client.fm.getIntentStatus(fabricId="fab1")
print("Intent Status:", status)

# --- Day 2: Config Lifecycle Management ---

# Backup current device configuration
backup = client.fm.backupConfig({
    "data": [
        {"ip": "xx.xx.xx.xx", "label": "my-backup"}
    ]
})
print("Backup Config:", backup)

# Diff current config against last known good state
diff = client.fm.diffConfig(fabricId="fab1")
print("Config Diff:", diff)

# Restore a previously backed-up configuration
client.fm.restoreConfig({"fabricId": "fab1", "backupId": "bkp123"})

# Commit pending configuration changes
client.fm.commitConfig({"fabricId": "fab1"})

# Check config operation status
config_status = client.fm.getConfigStatus(fabricId="fab1")
print("Config Status:", config_status)

# --- Device Operations ---

# List devices in a fabric
devices = client.fm.listDevice(fabricId="fab1")
print("Devices:", devices)

# Reboot a device
client.fm.rebootDevice({"deviceId": "dev1"})

# Upgrade device firmware
client.fm.upgradeDevice({"deviceId": "dev1", "version": "4.2.0"})

# --- Tenant Management ---

# Add a tenant (logical network partition)
client.fm.addTenant({"fabricId": "fab1", "tenantName": "tenant-a"})

# List tenants
tenants = client.fm.listTenant(fabricId="fab1")
print("Tenants:", tenants)

# --- Job Tracking ---

# List all async jobs
jobs = client.fm.listJobs()
print("Jobs:", jobs)

# Get status of a specific job
job_status = client.fm.getJobStatus(jobId="job-001")
print("Job Status:", job_status)
```

---

## Health API

> These APIs provide telemetry and health metrics for SONiC-managed network devices, including CPU usage, interface states, and fabric-wide health summaries.

```python
# List all managed devices
devices = client.health.device_list()
print("Devices:", devices)

# Device health info over a time range
info = client.health.device_info(
    from_date="2026-03-23 00:56:30",
    to_date="2026-03-24 09:56:30",
    window_size="1 hour",
    device_address="xx:xx:xx:xx:xx:xx"
)
print("Device Info:", info)

# Mega API — aggregated health telemetry over a time window
mega = client.health.mega(
    from_date="2026-03-23 12:05:44",
    to_date="2026-03-24 12:05:44",
    window_size="1 day",
    device_address="xx:xx:xx:xx:xx:xx"
)
print("Mega:", mega)

# Top CPU-consuming services on a device
top_services = client.health.top_cpu_consuming_services(
    device_address="xx:xx:xx:xx:xx:xx"
)
print("Top CPU Consuming Services:", top_services)

# Fabric-wide health summary
fabric_health = client.health.fabric_wise_health()
print("Fabric Wise Health:", fabric_health)
```

---

## Inventory API

> Inventory APIs expose hardware and software details of SONiC devices including interfaces, NICs, peripherals, firmware versions, and link topology.

```python
# Device interfaces
interfaces = client.inventory.device_interfaces(device_address="xx:xx:xx:xx:xx:xx")
print("Device Interfaces:", interfaces)

# Device peripherals (PSU, fans, etc.)
peripherals = client.inventory.device_peripherals(device_address="xx:xx:xx:xx:xx:xx")
print("Device Peripherals:", peripherals)

# Device info
device_info = client.inventory.device_info(device_address="xx:xx:xx:xx:xx:xx")
print("Device Info:", device_info)

# Firmware version
firmware = client.inventory.device_firmware(device_address="xx:xx:xx:xx:xx:xx")
print("Device Firmware:", firmware)

# Link topology info
link_info = client.inventory.link_info(device_address="xx:xx:xx:xx:xx:xx")
print("Link Info:", link_info)

# Interface flap events — useful for diagnosing instability
interface_flaps = client.inventory.interface_flaps(
    start_time="2026-03-23 02:09:36",
    end_time="2026-03-24 11:09:36",
    limit=10
)
print("Interface Flaps:", interface_flaps)

# Interface telemetry mega — aggregated interface stats
interface_mega = client.inventory.interface_mega()
print("Interface Mega:", interface_mega)

# NIC info
nic_info = client.inventory.nic_info(device_address="xx:xx:xx:xx:xx:xx")
print("NIC Info:", nic_info)

# Full device details
device_details = client.inventory.device_details(device_address="xx:xx:xx:xx:xx:xx")
print("Device Details:", device_details)

# Orchestration inventory details
inv_details_orchest = client.inventory.inv_details_orchest()
print("Inventory Details Orchestration:", inv_details_orchest)

# YAML config files per device
device_yaml_files = client.inventory.device_yaml_files()
print("Device YAML Files:", device_yaml_files)

# Condensed inventory summary
mini_inventory = client.inventory.mini_inventory()
print("Mini Inventory:", mini_inventory)
```

---

## Misc API

> Miscellaneous APIs expose global platform settings and feature flags.

```python
# Check if Fabric Manager is enabled
is_fm_enabled = client.misc.is_fm_enabled()
print("Is FM Enabled:", is_fm_enabled)

# World map topology data
world_map_data = client.misc.world_map_data()
print("World Map Data:", world_map_data)

# Check if AI assistant is enabled
is_ai_assistant_enabled = client.misc.is_ai_assistant_enabled()
print("Is AI Assistant Enabled:", is_ai_assistant_enabled)

# Retrieve illustrator YAML (topology visualization config)
illustrator_yaml = client.misc.get_illustrator_yaml()
print("Illustrator YAML:", illustrator_yaml)

# List regions
region_list = client.misc.region_list()
print("Region List:", region_list)

# Telemetry preferences
telemetry_preferences = client.misc.telemetry_preferences()
print("Telemetry Preferences:", telemetry_preferences)
```

---

## Traffic API

> Traffic APIs provide interface-level traffic telemetry for SONiC switches, including **PFC (Priority Flow Control)** — a lossless Ethernet mechanism used in data center networks to prevent buffer overflow on specific traffic priorities.

```python
# Check if PFC is enabled on an interface
resp1 = client.traffic.is_interf_pfc_enabled(
    device_address="xx:xx:xx:xx:xx:xx",
    ifname="Ethernet1"
)
print("PFC Enabled:", resp1)

# List traffic profiles
resp2 = client.traffic.traffic_list(device_address="xx:xx:xx:xx:xx:xx")
print("Traffic List:", resp2)

# Interface details with layer and licensing context
resp3 = client.traffic.get_interface_details(
    device_address="xx:xx:xx:xx:xx:xx",
    hostname="switch1",
    ipaddress="192.168.1.1",
    layer="L2",
    time_bucket="5m",
    window_size=10,
    license_="standard"
)
print("Interface Details:", resp3)

# Detailed interface telemetry over a time range
resp4 = client.traffic.interface_details(
    from_date="2024-06-01T00:00:00Z",
    to_date="2024-06-02T00:00:00Z",
    window_size=10,
    device_address="xx:xx:xx:xx:xx:xx",
    active_tab="tab1",
    ifname="Ethernet1"
)
print("Interface Details (Time Range):", resp4)

# Aggregated traffic telemetry (mega)
resp5 = client.traffic.traffic_mega(
    from_date="2024-06-01T00:00:00Z",
    to_date="2024-06-02T00:00:00Z",
    window_size=10,
    device_address="xx:xx:xx:xx:xx:xx",
    active_tab="tab1",
    ifname="Ethernet1"
)
print("Traffic Mega:", resp5)

# QoS priority mapping for an interface
resp6 = client.traffic.priority_mapping(
    device_address="xx:xx:xx:xx:xx:xx",
    ifname="Ethernet1"
)
print("Priority Mapping:", resp6)
```



---

## Copyright & Disclaimer

&copy; 2026 Aviz Networks. All rights reserved.


For questions, support, or feature requests, please open an issue or contact the maintainers via [GitHub](https://github.com/AvizNetworks/ones-pyapi).

---
