From 91b6606e3f10d72e991213a6ef70955e9a1f241f Mon Sep 17 00:00:00 2001
From: IluaAir <ilya@air.ru>
Date: Wed, 18 Feb 2026 00:55:43 +0300
Subject: [PATCH] Enhance BaseDevice methods with detailed parsing
 documentation

- Updated the `vlans`, `interfaces`, and `system` methods in the `BaseDevice` class to include comprehensive docstrings outlining expected raw data structures and error handling.
- Modified the `Interfaces` model in `contract.py` to allow optional fields for `ip_address` and `mask`, improving flexibility in interface definitions.
---
 oxi/interfaces/base.py     | 40 +++++++++++++++++++++++++++++++++++---
 oxi/interfaces/contract.py |  5 +++--
 2 files changed, 40 insertions(+), 5 deletions(-)

diff --git a/oxi/interfaces/base.py b/oxi/interfaces/base.py
index 5b40741..05adeeb 100644
--- a/oxi/interfaces/base.py
+++ b/oxi/interfaces/base.py
@@ -25,13 +25,47 @@ class BaseDevice(ABC):
         """
 
     @abstractmethod
-    def vlans(self) -> list["Vlans"]: ...
+    def vlans(self) -> list["Vlans"]:
+        f"""
+        Parse VLAN configuration from self._raw['vlans'].
+
+        Expected raw structure:
+            [{"id": 10, "description": "MGMT"}, {"id": 15, "name": "SSH"}, ...]
+
+        Returns:
+            list[Vlans]: список VLAN из секции vlans,
+                пустой список если секция отсутствует.
+
+        Raises:
+            ValueError: если _raw содержит некорректные данные.
+        """
+        ...
 
     @abstractmethod
-    def interfaces(self) -> list["Interfaces"]: ...
+    def interfaces(self) -> list["Interfaces"]:
+        f"""
+        Parse Interface configuration from self._raw['interfaces'].
+
+        Expected raw structure:
+            [{"name": "GEthernet1/0/1", "ip_address": "192.168.1.1", "mask": "24", "description": "IPBB interface"}]
+        
+        Raises:
+            ValueError: если _raw содержит некорректные данные.
+        """
+        ...
 
     @abstractmethod
-    def system(self) -> "System": ...
+    def system(self) -> "System":
+        """
+        Parse System configuration from self._raw['system'].
+
+        Expected raw structure:
+            {"model":"RB951Ui-2nD", serial_number: "B88C0B31117B", "version": "7.12.1"}
+
+        Raises:
+            ValueError: если _raw содержит некорректные данные.
+        """
+        ...
 
     def _load_template(self):
         path = Path(__file__).parent / "template" / self.template
diff --git a/oxi/interfaces/contract.py b/oxi/interfaces/contract.py
index 9869500..34b36df 100644
--- a/oxi/interfaces/contract.py
+++ b/oxi/interfaces/contract.py
@@ -3,8 +3,9 @@ from pydantic import BaseModel, Field
 
 
 class Interfaces(BaseModel):
-    ip_address: IPv4Address
-    mask: int
+    name: str
+    ip_address: IPv4Address | None = None
+    mask: int | None = None
     description: str