python-netgear-switch-library 0.0.post350__tar.gz → 0.0.post352__tar.gz

{python_netgear_switch_library-0.0.post350 → python_netgear_switch_library-0.0.post352}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-netgear-switch-library
-Version: 0.0.post350
+Version: 0.0.post352
 Summary: Python library and CLI to query and control Netgear switches over SNMP, NSDP and HTTP.
 Author-email: Tim Ansell <me@mith.ro>
 License-Expression: Apache-2.0

{python_netgear_switch_library-0.0.post350 → python_netgear_switch_library-0.0.post352}/src/netgear_switch/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '0.0.post350'
-__version_tuple__ = version_tuple = (0, 0, 'post350')
+__version__ = version = '0.0.post352'
+__version_tuple__ = version_tuple = (0, 0, 'post352')
 
 __commit_id__ = commit_id = None

{python_netgear_switch_library-0.0.post350 → python_netgear_switch_library-0.0.post352}/src/netgear_switch/models.py

@@ -38,6 +38,17 @@ class PortStatus:
     # older tests) keep constructing without it; a backend that cannot read
     # ifAlias (NSDP, HTTP) leaves it honestly None rather than fabricating "".
     description: str | None = None
+    #: Whether the link negotiated FULL duplex. ``None`` when the backend cannot
+    #: tell -- a down port has no negotiated duplex, and not every backend
+    #: reports it at all. Measured 2026-08-02: the M4300's EtherLike-MIB dot3
+    #: table exposes only error counters, NOT dot3StatsDuplexStatus (column 19
+    #: is absent), so SNMP cannot answer this and leaves it None. The FASTPATH
+    #: CLI does: `show port all` reports "1000 Full" in its Physical Status
+    #: column, carrying speed and duplex together.
+    full_duplex: bool | None = None
+    #: Whether IEEE 802.3x flow control is enabled on the port ("Flow Mode" in
+    #: `show port all`). ``None`` where the backend does not report it.
+    flow_control: bool | None = None
 
 
 @dataclass(frozen=True)

{python_netgear_switch_library-0.0.post350 → python_netgear_switch_library-0.0.post352}/src/netgear_switch/protocols/cli/parse.py

@@ -244,6 +244,11 @@ def parse_version(text: str, models: Mapping[str, SwitchModel]) -> DetectedModel
 #   Link Status | Link Trap | LACP Mode | Flow Mode
 _PORT_INTF, _PORT_TYPE, _PORT_ADMIN = 0, 1, 2
 _PORT_PHYS_MODE, _PORT_PHYS_STATUS, _PORT_LINK = 3, 4, 5
+# Flow Mode is the LAST column of `show port all` (Intf, Type, Admin Mode,
+# Physical Mode, Physical Status, Link Status, Link Trap, LACP Mode, Flow
+# Mode). Indexed from the end so a firmware that omits an intermediate
+# column cannot silently shift it.
+_PORT_FLOW = -1
 
 _SPEED_RE = re.compile(r"(\d+)\s*([GgMm]?)")
 
@@ -261,13 +266,30 @@ def _speed_mbps(phys_status: str) -> int | None:
     return value * 1000 if m.group(2).upper() == "G" else value
 
 
+def _duplex(phys_status: str) -> bool | None:
+    """FULL/HALF from the Physical Status cell, e.g. "1000 Full" -> True.
+
+    Blank on a down port, which has no negotiated duplex -- honestly None rather
+    than a fabricated False.
+    """
+    text = phys_status.strip().lower()
+    if "full" in text:
+        return True
+    if "half" in text:
+        return False
+    return None
+
+
 def parse_port_status(text: str) -> list[PortStatus]:
     """``show port all`` -> per physical-port ``PortStatus``.
 
     ``admin_enabled`` = Admin Mode == "Enable"; ``link_up`` = Link Status ==
-    "Up"; ``speed_mbps`` from Physical Status (None when blank/down). ``lag N``
-    aggregation rows are skipped (not physical ports). ``description`` is
-    honestly ``None``: this command carries no ifAlias column.
+    "Up"; ``speed_mbps`` and ``full_duplex`` both from Physical Status, which
+    carries them together ("1000 Full"); ``flow_control`` from the Flow Mode
+    column. All three are ``None`` on a down port, which has negotiated nothing.
+    ``lag N`` aggregation rows are skipped (not physical ports).
+    ``description`` is honestly ``None``: this command carries no ifAlias
+    column.
     """
     out: list[PortStatus] = []
     for cells in iter_table_rows(text):
@@ -288,6 +310,16 @@ def parse_port_status(text: str) -> list[PortStatus]:
                     else None
                 ),
                 description=None,
+                full_duplex=(
+                    _duplex(cells[_PORT_PHYS_STATUS])
+                    if cells[_PORT_LINK].strip().lower() == "up"
+                    else None
+                ),
+                flow_control=(
+                    cells[_PORT_FLOW].strip().lower() == "enable"
+                    if len(cells) > _PORT_LINK + 1
+                    else None
+                ),
             )
         )
     return out

{python_netgear_switch_library-0.0.post350 → python_netgear_switch_library-0.0.post352}/src/netgear_switch/virtual/seed.py

@@ -31,6 +31,8 @@ from .state import (
     PoeSim,
     PortSim,
     SensorSim,
+    SyslogCollectorSim,
+    SyslogSim,
     VirtualSwitchState,
     VlanMembershipPageSim,
     VlanSim,
@@ -1237,6 +1239,13 @@ def seed_gsm7252ps() -> VirtualSwitchState:
         # capture of this switch (tests/fixtures/http/gsm7252ps_sysInfo.html).
         serial="2BW20A47000CC",
         firmware="10.0.0.53",
+        # MEASURED 2026-08-02 on 10.1.5.22: identical to the m4300 pair --
+        # enabled, port 514, one collector 10.1.5.1 info(6) 514 Active.
+        syslog=SyslogSim(
+            admin_mode=1,
+            local_port=514,
+            collectors=[SyslogCollectorSim("10.1.5.1", 514, 6)],
+        ),
         hostname="sw-netgear-gsm7252ps-s1.welland.mithis.com",
         nsdp_mac=b"\xe0\x91\xf5\x0c\xd6\xdb",  # captured System MAC Address
         # Illustrative sysDescr text -- NOT a captured real firmware string;
@@ -1798,6 +1807,10 @@ def seed_gsm7228ps() -> VirtualSwitchState:
         lldp=lldp,
         mgmt=mgmt,
         model_name="GSM7228PS",
+        # MEASURED 2026-08-02 on 10.1.5.11: the vendor admin-mode column
+        # reads 2 (disabled) and the host table is EMPTY -- this switch has
+        # no collector configured, which is why get_syslog returns none.
+        syslog=SyslogSim(admin_mode=2, local_port=514, collectors=[]),
         hostname="sw-netgear-s3300-1",
         nsdp_mac=b"\x08\xbd\x43\x6b\xb8\xd8",  # captured base/System MAC
         # REAL captured identity: the S3300-52X-PoE+'s actual sysDescr and
@@ -2397,6 +2410,14 @@ def seed_m4300_24x() -> VirtualSwitchState:
     state = VirtualSwitchState(
         # Measured 2026-08-02: sysName and `show hosts` both report this on the
         # real switch. Was empty here, which no real FASTPATH switch is.
+        # MEASURED 2026-08-02 on 10.1.5.13: `show logging` reports
+        # "Syslog Logging : enabled" and local port 514, and
+        # `show logging hosts` one row 10.1.5.1 / info(6) / 514 / Active.
+        syslog=SyslogSim(
+            admin_mode=1,
+            local_port=514,
+            collectors=[SyslogCollectorSim("10.1.5.1", 514, 6)],
+        ),
         hostname="sw-netgear-m4300-24x",
         model_key="m4300-24x",
         ports=ports,

{python_netgear_switch_library-0.0.post350 → python_netgear_switch_library-0.0.post352}/src/netgear_switch/virtual/state.py

@@ -155,6 +155,37 @@ class PortSim:
     flow_control: bool = True
 
 
+@dataclass
+class SyslogCollectorSim:
+    """One remote syslog collector row, as the vendor host table reports it.
+
+    Field values are SEEDED from a live switch, never computed: the severity is
+    the standard syslog number the device actually returns (6 for "info" on
+    m4300-24x, cross-checked against its own `show logging hosts`), and status 1
+    is what that command prints as "Active".
+    """
+
+    host: str
+    port: int
+    severity: int
+    status: int = 1
+
+
+@dataclass
+class SyslogSim:
+    """The switch's remote-logging state, as the vendor `.14` subtree reports it.
+
+    MEASURED 2026-08-02 -- see docs/superpowers/specs/. ``admin_mode`` is the
+    device's own enum (1 = enabled, 2 = disabled), kept as the raw integer
+    rather than a bool so the mock emits exactly what a real agent emits and the
+    reader's own decoding is what gets exercised.
+    """
+
+    admin_mode: int = 2
+    local_port: int = 514
+    collectors: list[SyslogCollectorSim] = field(default_factory=list)
+
+
 @dataclass
 class VlanSim:
     """One dot1q VLAN: display name plus egress-member and untagged port sets.
@@ -374,6 +405,10 @@ class VirtualSwitchState:
     serial: str = ""
     firmware: str = ""
     hostname: str = ""
+    #: Remote-logging state. Only meaningful for a model with a vendor subtree;
+    #: oid_map() projects it under <vendor base>.14 for those models only, which
+    #: is what makes gs728tpp (no vendor OIDs) correctly unable to answer.
+    syslog: SyslogSim = field(default_factory=SyslogSim)
     nsdp_password: str = "password"
     # Write-auth scheme this mock advertises via AUTH_V2_ENCPASS (0x0014), and
     # the ONLY scheme it accepts on a WRITE_REQUEST:
@@ -737,6 +772,20 @@ class VirtualSwitchState:
         # publishes no vendor subtree at all.
         m[oids.SYS_NAME] = ("OCTETSTR", self.hostname)
 
+        # Remote logging, under <vendor base>.14 -- the same columns the real
+        # agents publish, and ONLY for a model that has a vendor subtree. A
+        # model with none (gs728tpp) must stay unable to answer get_syslog here
+        # exactly as it is on the wire, rather than the mock inventing a reply.
+        if v is not None:
+            m[f"{v.base}.14.1.4.1.0"] = ("INTEGER", str(self.syslog.admin_mode))
+            m[f"{v.base}.14.1.4.3.0"] = ("Gauge32", str(self.syslog.local_port))
+            for index, col in enumerate(self.syslog.collectors, start=1):
+                m[f"{v.base}.14.1.4.5.1.2.{index}"] = ("INTEGER", "1")
+                m[f"{v.base}.14.1.4.5.1.3.{index}"] = ("OCTETSTR", col.host)
+                m[f"{v.base}.14.1.4.5.1.4.{index}"] = ("Gauge32", str(col.port))
+                m[f"{v.base}.14.1.4.5.1.5.{index}"] = ("INTEGER", str(col.severity))
+                m[f"{v.base}.14.1.4.5.1.7.{index}"] = ("INTEGER", str(col.status))
+
         for port, sim in self.ports.items():
             m[f"{oids.IF_ADMIN_STATUS}.{port}"] = ("INTEGER", "1" if sim.admin else "2")
             m[f"{oids.IF_OPER_STATUS}.{port}"] = ("INTEGER", "1" if sim.link else "2")

python_netgear_switch_library-0.0.post352/tests/virtual/test_syslog_fidelity.py

@@ -0,0 +1,68 @@
+# tests/virtual/test_syslog_fidelity.py
+"""The fake must answer ``get_syslog`` exactly as the real switches did.
+
+Every expected value below was READ OFF A LIVE DEVICE on 2026-08-02 and
+cross-checked against that switch's own ``show logging`` / ``show logging
+hosts``. They are transcribed here, not computed: a mock that derived them with
+the same code under test could only ever agree with itself (principle 5).
+
+The gs728tpp row is the important one. It has no Netgear vendor subtree at all,
+the logging columns are vendor-only, and the reader refuses BY NAME rather than
+returning an empty config -- because "no collectors configured" and "this
+backend cannot tell you" are different answers and must not collapse into one.
+"""
+
+from __future__ import annotations
+
+import pytest
+
+from netgear_switch.errors import UnsupportedCapabilityError
+from netgear_switch.registry import get_model
+from netgear_switch.snmp_read import SnmpReader
+from netgear_switch.transport.sync.snmp_netsnmp_cli import NetsnmpCliClient
+from netgear_switch.virtual.server import VirtualSwitch
+
+#: model -> (enabled, local_port, [(host, port, severity, active)])
+#: transcribed from the live reads.
+MEASURED = {
+    # 10.1.5.13, `show logging hosts`: 1  10.1.5.1  info  514  Active
+    "m4300-24x": (True, 514, [("10.1.5.1", 514, 6, True)]),
+    # 10.1.5.22, same row (its host table prints five columns, not eight)
+    "gsm7252ps": (True, 514, [("10.1.5.1", 514, 6, True)]),
+    # 10.1.5.11: admin-mode column reads 2, and the host table is empty
+    "gsm7228ps": (False, 514, []),
+}
+
+
+def _reader(mock: VirtualSwitch, key: str) -> SnmpReader:
+    client = NetsnmpCliClient(f"{mock.host}:{mock.port}", mock.community)
+    return SnmpReader(client, get_model(key))
+
+
+@pytest.mark.parametrize("key", sorted(MEASURED))
+def test_fake_matches_the_live_switch(key: str) -> None:
+    enabled, local_port, collectors = MEASURED[key]
+    with VirtualSwitch(model=key) as mock:
+        cfg = _reader(mock, key).get_syslog()
+    assert cfg.enabled is enabled
+    assert cfg.local_port == local_port
+    assert [(s.host, s.port, s.severity, s.active) for s in cfg.servers] == collectors
+
+
+def test_severity_is_the_device_number_not_a_label() -> None:
+    """6 is what the column holds where the CLI prints "info".
+
+    Pinned separately because it is the one value a future refactor might be
+    tempted to "improve" into an enum name, breaking agreement with the wire.
+    """
+    with VirtualSwitch(model="m4300-24x") as mock:
+        cfg = _reader(mock, "m4300-24x").get_syslog()
+    assert cfg.servers[0].severity == 6
+
+
+def test_a_model_with_no_vendor_subtree_refuses_rather_than_answering_empty() -> None:
+    with (
+        VirtualSwitch(model="gs728tpp") as mock,
+        pytest.raises(UnsupportedCapabilityError, match="vendor"),
+    ):
+        _reader(mock, "gs728tpp").get_syslog()