Refactor Wave 5 NLRI qualifiers to packed-bytes-first pattern

Refactor all 5 NLRI qualifier classes to store packed bytes as primary
representation with factory methods for semantic construction:

- PathInfo: make_from_integer(), make_from_ip()
- RouteDistinguisher: make_from_elements() (removed fromElements alias)
- Labels: make_labels(list[int], bos)
- ESI: make_default(), make_esi()
- EthernetTag: make_etag(int)

Each class now:
- Takes packed bytes in __init__ with size validation
- Provides factory methods for semantic construction
- Uses @Property for backward-compatible attribute access
- Unpacks data on demand rather than storing both forms

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

Author: thomas-mangin

.claude/docs/plans/packed-attribute.md

@@ -108,8 +108,15 @@ class INET(NLRI):
 ### Wave 4: MP Attributes + BGP-LS + SR
 21-55. `mprnlri.py`, `mpurnlri.py`, `bgpls/*.py`, `sr/*.py`
 
-### Wave 5: Qualifiers
-56-60. `nlri/qualifier/path.py`, `rd.py`, `labels.py`, `esi.py`, `etag.py`
+### Wave 5: Qualifiers ✅ COMPLETE
+
+| File | Status | Factory Method |
+|------|--------|----------------|
+| `path.py` | ✅ Done | `PathInfo.make_from_integer(int)`, `PathInfo.make_from_ip(str)` |
+| `rd.py` | ✅ Done | `RouteDistinguisher.make_from_elements(prefix, suffix)` |
+| `labels.py` | ✅ Done | `Labels.make_labels(list[int], bos)` |
+| `esi.py` | ✅ Done | `ESI.make_default()`, `ESI.make_esi(bytes)` |
+| `etag.py` | ✅ Done | `EthernetTag.make_etag(int)` |
 
 ### Wave 6: NLRI Types
 61. **`src/exabgp/bgp/message/update/nlri/cidr.py`**

src/exabgp/bgp/message/update/nlri/inet.py

@@ -164,7 +164,7 @@ def unpack_nlri(
                     break
                 if label & LABEL_BOTTOM_OF_STACK_BIT:
                     break
-            nlri.labels = Labels(labels)
+            nlri.labels = Labels.make_labels(labels)
 
         if rd_size:
             mask -= rd_mask  # the route distinguisher

src/exabgp/bgp/message/update/nlri/qualifier/esi.py

@@ -7,7 +7,6 @@
 """
 
 from __future__ import annotations
-from typing import Type
 
 # TODO: take into account E-VPN specs that specify the role of the first bit of ESI
 # (since draft-ietf-l2vpn-evpn-05)
@@ -20,15 +19,29 @@ class ESI:
     DEFAULT = bytes([0x00] * LENGTH)  # All zeros
     MAX = bytes([0xFF] * LENGTH)  # All ones
 
-    def __init__(self, esi: bytes | None = None) -> None:
-        self.esi: bytes = self.DEFAULT if esi is None else esi
-        if len(self.esi) != self.LENGTH:
-            raise Exception(f'incorrect ESI, len {len(esi)} instead of {self.LENGTH}')  # type: ignore[arg-type]
+    def __init__(self, packed: bytes) -> None:
+        if len(packed) != self.LENGTH:
+            raise ValueError(f'ESI requires exactly {self.LENGTH} bytes, got {len(packed)}')
+        self._packed = packed
+
+    @classmethod
+    def make_esi(cls, esi_bytes: bytes) -> 'ESI':
+        """Create ESI from bytes."""
+        return cls(esi_bytes)
+
+    @classmethod
+    def make_default(cls) -> 'ESI':
+        """Create ESI with default value (all zeros)."""
+        return cls(cls.DEFAULT)
+
+    @property
+    def esi(self) -> bytes:
+        return self._packed
 
     def __eq__(self, other: object) -> bool:
         if not isinstance(other, ESI):
             return False
-        return self.esi == other.esi
+        return self._packed == other._packed
 
     def __lt__(self, other: object) -> bool:
         raise RuntimeError('comparing ESI for ordering does not make sense')
@@ -43,24 +56,24 @@ def __ge__(self, other: object) -> bool:
         raise RuntimeError('comparing ESI for ordering does not make sense')
 
     def __str__(self) -> str:
-        if self.esi == self.DEFAULT:
+        if self._packed == self.DEFAULT:
             return '-'
-        return ':'.join('{:02x}'.format(_) for _ in self.esi)
+        return ':'.join('{:02x}'.format(_) for _ in self._packed)
 
     def __repr__(self) -> str:
         return self.__str__()
 
     def pack_esi(self) -> bytes:
-        return self.esi
+        return self._packed
 
     def __len__(self) -> int:
         return self.LENGTH
 
     def __hash__(self) -> int:
-        return hash(self.esi)
+        return hash(self._packed)
 
     @classmethod
-    def unpack_esi(cls: Type[ESI], data: bytes) -> ESI:
+    def unpack_esi(cls, data: bytes) -> 'ESI':
         return cls(data[: cls.LENGTH])
 
     def json(self, compact: bool = False) -> str:

src/exabgp/bgp/message/update/nlri/qualifier/etag.py

@@ -10,22 +10,33 @@
 # (since draft-ietf-l2vpn-evpn-05)
 
 from __future__ import annotations
-from typing import Type
 
 from struct import pack
 from struct import unpack
 
 
 class EthernetTag:
     MAX = pow(2, 32) - 1
+    LENGTH = 4
 
-    def __init__(self, tag: int = 0) -> None:
-        self.tag: int = tag
+    def __init__(self, packed: bytes) -> None:
+        if len(packed) != self.LENGTH:
+            raise ValueError(f'EthernetTag requires exactly {self.LENGTH} bytes, got {len(packed)}')
+        self._packed = packed
+
+    @classmethod
+    def make_etag(cls, tag: int) -> 'EthernetTag':
+        """Create EthernetTag from integer value."""
+        return cls(pack('!L', tag))
+
+    @property
+    def tag(self) -> int:
+        return unpack('!L', self._packed)[0]
 
     def __eq__(self, other: object) -> bool:
         if not isinstance(other, EthernetTag):
             return False
-        return self.tag == other.tag
+        return self._packed == other._packed
 
     def __lt__(self, other: object) -> bool:
         raise RuntimeError('comparing EthernetTag for ordering does not make sense')
@@ -46,17 +57,17 @@ def __repr__(self) -> str:
         return repr(self.tag)
 
     def pack_etag(self) -> bytes:
-        return pack('!L', self.tag)
+        return self._packed
 
     def __len__(self) -> int:
-        return 4
+        return self.LENGTH
 
     def __hash__(self) -> int:
-        return hash(self.tag)
+        return hash(self._packed)
 
     @classmethod
-    def unpack_etag(cls: Type[EthernetTag], data: bytes) -> EthernetTag:
-        return cls(unpack('!L', data[:4])[0])
+    def unpack_etag(cls, data: bytes) -> 'EthernetTag':
+        return cls(data[: cls.LENGTH])
 
     def json(self, compact: bool = False) -> str:
         return '"ethernet-tag": {}'.format(self.tag)

src/exabgp/bgp/message/update/nlri/qualifier/labels.py

@@ -6,7 +6,7 @@
 """
 
 from __future__ import annotations
-from typing import ClassVar, Type
+from typing import ClassVar
 
 from struct import pack
 from struct import unpack
@@ -25,98 +25,120 @@ class Labels:
 
     NOLABEL: ClassVar['Labels']
 
-    def __init__(self, labels: list[int], bos: bool = True, raw_labels: list[int] | None = None) -> None:
-        self.labels: list[int] = labels
-        self.raw_labels: list[int] = raw_labels if raw_labels else []
-        packed = []
-        if raw_labels:
-            for label in raw_labels:
-                packed.append(pack('!L', label)[1:])
-            # fill self.labels as well, not for packing, but to allow
-            # consistent string representations
-            if not self.labels:
-                self.labels = [x >> 4 for x in raw_labels]
-        else:
-            for label in labels:
-                # shift to 20 bits of the label to be at the top of three bytes and then truncate.
-                packed.append(pack('!L', label << 4)[1:])
-            # Mark the bottom of stack with the bit
-            if packed and bos:
-                packed.pop()
-                packed.append(pack('!L', (label << 4) | 1)[1:])
-            self.raw_labels = [0 for _ in self.labels]
-        self.packed: bytes = b''.join(packed)
-        self._len: int = len(self.packed)
+    def __init__(self, packed: bytes) -> None:
+        if len(packed) % 3 != 0:
+            raise ValueError(f'Labels packed data must be multiple of 3 bytes, got {len(packed)}')
+        self._packed = packed
+
+    @classmethod
+    def make_labels(cls, labels: list[int], bos: bool = True) -> 'Labels':
+        """Create Labels from list of label integers."""
+        if not labels:
+            return cls(b'')
+        packed_parts = []
+        for i, label in enumerate(labels):
+            # shift to 20 bits of the label to be at the top of three bytes
+            value = label << 4
+            # Mark the bottom of stack with the bit on last label
+            if bos and i == len(labels) - 1:
+                value |= 1
+            packed_parts.append(pack('!L', value)[1:])
+        return cls(b''.join(packed_parts))
+
+    @property
+    def labels(self) -> list[int]:
+        """Extract label values from packed bytes."""
+        result = []
+        data = self._packed
+        while len(data) >= 3:
+            raw = unpack('!L', bytes([0]) + data[:3])[0]
+            result.append(raw >> 4)
+            data = data[3:]
+        return result
+
+    @property
+    def raw_labels(self) -> list[int]:
+        """Extract raw 24-bit values (includes TC/S bits) from packed bytes."""
+        result = []
+        data = self._packed
+        while len(data) >= 3:
+            raw = unpack('!L', bytes([0]) + data[:3])[0]
+            result.append(raw)
+            data = data[3:]
+        return result
 
     def __eq__(self, other: object) -> bool:
         if not isinstance(other, Labels):
             return False
-        return self.labels == other.labels
+        return self._packed == other._packed
 
     def __lt__(self, other: object) -> bool:
-        raise RuntimeError('comparing EthernetTag for ordering does not make sense')
+        raise RuntimeError('comparing Labels for ordering does not make sense')
 
     def __le__(self, other: object) -> bool:
-        raise RuntimeError('comparing EthernetTag for ordering does not make sense')
+        raise RuntimeError('comparing Labels for ordering does not make sense')
 
     def __gt__(self, other: object) -> bool:
-        raise RuntimeError('comparing EthernetTag for ordering does not make sense')
+        raise RuntimeError('comparing Labels for ordering does not make sense')
 
     def __ge__(self, other: object) -> bool:
-        raise RuntimeError('comparing EthernetTag for ordering does not make sense')
+        raise RuntimeError('comparing Labels for ordering does not make sense')
 
     def pack_labels(self) -> bytes:
-        return self.packed
+        return self._packed
 
     def __len__(self) -> int:
-        return self._len
+        return len(self._packed)
 
     def json(self) -> str:
-        if len(self.labels) >= 1:
+        labels = self.labels
+        raw_labels = self.raw_labels
+        if len(labels) >= 1:
             return '"label": [ {} ]'.format(
                 ', '.join(
-                    [
-                        '[%d%s]' % (label, opt_raw_label(raw, ', %d'))
-                        for (label, raw) in zip(self.labels, self.raw_labels)
-                    ],
+                    ['[%d%s]' % (label, opt_raw_label(raw, ', %d')) for (label, raw) in zip(labels, raw_labels)],
                 )
             )
         return ''
 
     def __str__(self) -> str:
-        if len(self.labels) > 1:
+        labels = self.labels
+        raw_labels = self.raw_labels
+        if len(labels) > 1:
             return ' label [ {} ]'.format(
                 ' '.join(
-                    ['%d%s' % (label, opt_raw_label(raw)) for (label, raw) in zip(self.labels, self.raw_labels)],
+                    ['%d%s' % (label, opt_raw_label(raw)) for (label, raw) in zip(labels, raw_labels)],
                 )
             )
-        if len(self.labels) == 1:
-            return ' label %d%s' % (self.labels[0], opt_raw_label(self.raw_labels[0]))
+        if len(labels) == 1:
+            return ' label %d%s' % (labels[0], opt_raw_label(raw_labels[0]))
         return ''
 
     def __repr__(self) -> str:
-        if len(self.labels) > 1:
+        labels = self.labels
+        raw_labels = self.raw_labels
+        if len(labels) > 1:
             return '[ {} ]'.format(
                 ','.join(
-                    ['%d%s' % (label, opt_raw_label(raw)) for (label, raw) in zip(self.labels, self.raw_labels)],
+                    ['%d%s' % (label, opt_raw_label(raw)) for (label, raw) in zip(labels, raw_labels)],
                 )
             )
-        if len(self.labels) == 1:
-            return '%d%s' % (self.labels[0], opt_raw_label(self.raw_labels[0]))
+        if len(labels) == 1:
+            return '%d%s' % (labels[0], opt_raw_label(raw_labels[0]))
         return '[ ]'
 
     @classmethod
-    def unpack_labels(cls: Type[Labels], data: bytes) -> Labels:
-        labels = []
-        raw_labels = []
-        while len(data):
-            label = unpack('!L', bytes([0]) + data[:3])[0]
+    def unpack_labels(cls, data: bytes) -> 'Labels':
+        """Unpack labels from data, stopping at bottom-of-stack bit."""
+        packed_parts = []
+        while len(data) >= 3:
+            chunk = data[:3]
+            packed_parts.append(chunk)
             data = data[3:]
-            labels.append(label >> 4)
-            raw_labels.append(label)
-            if label & 0x001:
+            raw = unpack('!L', bytes([0]) + chunk)[0]
+            if raw & 0x001:  # bottom-of-stack bit
                 break
-        return cls(labels, raw_labels=raw_labels)
+        return cls(b''.join(packed_parts))
 
 
-Labels.NOLABEL = Labels([])
+Labels.NOLABEL = Labels(b'')