Add OFDMA ranging status string enum

- Map docsIf31CmStatusOfdmaUsRangingStatus to enum
- Update OFDMA stats docs to show string values
- Add tests for OFDMA ranging status mapping

Author: mgarcia01752

docs/api/fast-api/single/us/ofdma/stats.md

@@ -70,7 +70,7 @@ Retrieves statistics and configuration parameters for upstream OFDMA channels fr
       "docsIf31CmStatusOfdmaUsRangingAborteds": 0,
       "docsIf31CmStatusOfdmaUsT3Exceededs": 0,
       "docsIf31CmStatusOfdmaUsIsMuted": false,
-      "docsIf31CmStatusOfdmaUsRangingStatus": "4"
+      "docsIf31CmStatusOfdmaUsRangingStatus": "success"
     }
   }
 ]
@@ -98,7 +98,7 @@ Retrieves statistics and configuration parameters for upstream OFDMA channels fr
 | `docsIf31CmStatusOfdmaUsRangingAborteds`        | int   | Number of aborted ranging attempts              |
 | `docsIf31CmStatusOfdmaUsT3Exceededs`            | int   | Number of times T3 retries exceeded             |
 | `docsIf31CmStatusOfdmaUsIsMuted`                | bool  | Indicates if the upstream is muted              |
-| `docsIf31CmStatusOfdmaUsRangingStatus`          | str   | Current ranging status (e.g., `4` = success)    |
+| `docsIf31CmStatusOfdmaUsRangingStatus`          | string | Ranging state name (e.g., `success`).           |
 
 
 ## Notes

src/pypnm/docsis/data_type/DocsIf31CmUsOfdmaChanEntry.py

@@ -2,12 +2,13 @@
 from __future__ import annotations
 
 # SPDX-License-Identifier: Apache-2.0
-# Copyright (c) 2025 Maurice Garcia
+# Copyright (c) 2025-2026 Maurice Garcia
 import logging
 from collections.abc import Callable
 
 from pydantic import BaseModel
 
+from pypnm.lib.constants import DocsIf31CmStatusOfdmaUsRangingStatus
 from pypnm.lib.types import ChannelId, FrequencyHz
 from pypnm.snmp.snmp_v2c import Snmp_v2c
 
@@ -30,7 +31,7 @@ class DocsIf31CmUsOfdmaChan(BaseModel):
     docsIf31CmStatusOfdmaUsRangingAborteds: int | None = None
     docsIf31CmStatusOfdmaUsT3Exceededs: int | None = None
     docsIf31CmStatusOfdmaUsIsMuted: bool | None = None
-    docsIf31CmStatusOfdmaUsRangingStatus: str | None = None
+    docsIf31CmStatusOfdmaUsRangingStatus: DocsIf31CmStatusOfdmaUsRangingStatus | None = None
 
 class DocsIf31CmUsOfdmaChanEntry(BaseModel):
     index: int
@@ -92,7 +93,9 @@ async def fetch(field: str, cast: Callable | None = None) -> None | int | float
             docsIf31CmStatusOfdmaUsRangingAborteds          =   await fetch("docsIf31CmStatusOfdmaUsRangingAborteds", int),
             docsIf31CmStatusOfdmaUsT3Exceededs              =   await fetch("docsIf31CmStatusOfdmaUsT3Exceededs", int),
             docsIf31CmStatusOfdmaUsIsMuted                  =   await fetch("docsIf31CmStatusOfdmaUsIsMuted", Snmp_v2c.truth_value),
-            docsIf31CmStatusOfdmaUsRangingStatus            =   await fetch("docsIf31CmStatusOfdmaUsRangingStatus", str)
+            docsIf31CmStatusOfdmaUsRangingStatus            =   DocsIf31CmStatusOfdmaUsRangingStatus.from_int(
+                await fetch("docsIf31CmStatusOfdmaUsRangingStatus", int),
+            )
         )
 
         try:

src/pypnm/lib/constants.py

@@ -160,6 +160,34 @@ def from_int(cls, value: int | None) -> DocsIf3CmStatusUsRangingStatus | None:
             case _:
                 return None
 
+class DocsIf31CmStatusOfdmaUsRangingStatus(StringEnum):
+    OTHER = "other"
+    ABORTED = "aborted"
+    RETRIES_EXCEEDED = "retriesExceeded"
+    SUCCESS = "success"
+    CONTINUE = "continue"
+    TIMEOUT_T4 = "timeoutT4"
+
+    @classmethod
+    def from_int(cls, value: int | None) -> DocsIf31CmStatusOfdmaUsRangingStatus | None:
+        if value is None:
+            return None
+        match value:
+            case 1:
+                return cls.OTHER
+            case 2:
+                return cls.ABORTED
+            case 3:
+                return cls.RETRIES_EXCEEDED
+            case 4:
+                return cls.SUCCESS
+            case 5:
+                return cls.CONTINUE
+            case 6:
+                return cls.TIMEOUT_T4
+            case _:
+                return None
+
 class DocsIf31CmDsOfdmChanIndicator(StringEnum):
     OTHER = "other"
     PRIMARY = "primary"
@@ -217,6 +245,7 @@ def from_int(cls, value: int | None) -> DocsIf31CmDsOfdmChanIndicator | None:
     "DocsIfDownChannelModulation",
     "DocsIfDownChannelInterleave",
     "DocsIf3CmStatusUsRangingStatus",
+    "DocsIf31CmStatusOfdmaUsRangingStatus",
     "DocsIf31CmDsOfdmChanIndicator",
     "DEFAULT_SPECTRUM_ANALYZER_INDICES",
     "FEC_SUMMARY_TYPE_STEP_SECONDS", "FEC_SUMMARY_TYPE_LABEL",

tests/test_docs_if31_cm_ds_ofdm_chan_indicator.py

@@ -0,0 +1,33 @@
+# SPDX-License-Identifier: Apache-2.0
+# Copyright (c) 2026 Maurice Garcia
+
+from __future__ import annotations
+
+import pytest
+
+from pypnm.docsis.data_type.DocsIf31CmDsOfdmChanEntry import DocsIf31CmDsOfdmChanChannelEntry
+from pypnm.lib.constants import DocsIf31CmDsOfdmChanIndicator
+from pypnm.snmp.snmp_v2c import Snmp_v2c
+
+
+class _FakeSnmp:
+    def __init__(self, values: dict[str, str]) -> None:
+        self._values = values
+
+    async def get(self, oid: str) -> tuple[str, str]:
+        return (oid, self._values.get(oid, ""))
+
+
+@pytest.mark.asyncio
+async def test_docs_if31_cm_ds_ofdm_chan_indicator_maps_nonprimary(monkeypatch: pytest.MonkeyPatch) -> None:
+    values = {
+        "docsIf31CmDsOfdmChanChanIndicator.1": "4",
+        "docsIf31CmDsOfdmChanChannelId.1": "1",
+        "docsIf31CmDsOfdmChanSubcarrierSpacing.1": "25",
+    }
+
+    fake = _FakeSnmp(values)
+    monkeypatch.setattr(Snmp_v2c, "get_result_value", lambda res: res[1])
+
+    result = await DocsIf31CmDsOfdmChanChannelEntry.from_snmp(1, fake)
+    assert result.entry.docsIf31CmDsOfdmChanChanIndicator == DocsIf31CmDsOfdmChanIndicator.NON_PRIMARY

tests/test_docs_if31_cm_status_ofdma_us_ranging_status.py

@@ -0,0 +1,36 @@
+# SPDX-License-Identifier: Apache-2.0
+# Copyright (c) 2026 Maurice Garcia
+
+from __future__ import annotations
+
+import pytest
+
+from pypnm.docsis.data_type.DocsIf31CmUsOfdmaChanEntry import DocsIf31CmUsOfdmaChanEntry
+from pypnm.lib.constants import DocsIf31CmStatusOfdmaUsRangingStatus
+from pypnm.snmp.snmp_v2c import Snmp_v2c
+
+
+class _FakeSnmp:
+    def __init__(self, values: dict[str, str]) -> None:
+        self._values = values
+
+    async def get(self, oid: str) -> tuple[str, str]:
+        return (oid, self._values.get(oid, ""))
+
+
+@pytest.mark.asyncio
+async def test_docs_if31_cm_status_ofdma_us_ranging_status_maps_success(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    values = {
+        "docsIf31CmStatusOfdmaUsRangingStatus.1": "4",
+        "docsIf31CmUsOfdmaChanChannelId.1": "1",
+    }
+
+    fake = _FakeSnmp(values)
+    monkeypatch.setattr(Snmp_v2c, "get_result_value", lambda res: res[1])
+
+    result = await DocsIf31CmUsOfdmaChanEntry.from_snmp(1, fake)
+    assert result.entry.docsIf31CmStatusOfdmaUsRangingStatus == (
+        DocsIf31CmStatusOfdmaUsRangingStatus.SUCCESS
+    )