From 4e80bf2c7622c88cb1baf84c0c68e71570ac59d0 Mon Sep 17 00:00:00 2001
From: Ryan Malloy <ryan@supported.systems>
Date: Fri, 13 Feb 2026 01:17:46 -0700
Subject: [PATCH] Add resolve_pin() docstring and loop labels example

- Document return contract, resolution precedence, and type-sensitivity
  note in resolve_pin() docstring
- Add ex17_loop_labels.yml: RS-232 loopback adapter demonstrating
  loops with pin labels, mixed number+label, and label-based connections
---
 examples/ex17_loop_labels.yml | 23 +++++++++++++++++++++++
 src/wireviz/DataClasses.py    | 18 ++++++++++++++++--
 2 files changed, 39 insertions(+), 2 deletions(-)
 create mode 100644 examples/ex17_loop_labels.yml

diff --git a/examples/ex17_loop_labels.yml b/examples/ex17_loop_labels.yml
new file mode 100644
index 0000000..df635f5
--- /dev/null
+++ b/examples/ex17_loop_labels.yml
@@ -0,0 +1,23 @@
+# Connector loops using pin labels
+# RS-232 loopback adapter: RTS-CTS and DSR-DTR-DCD jumpered,
+# with TX/RX/GND passed through to a cable.
+
+connectors:
+  X1:
+    type: D-Sub
+    subtype: female
+    pinlabels: [DCD, RX, TX, DTR, GND, DSR, RTS, CTS, RI]
+    loops:
+      - [RTS, CTS]      # pin labels instead of numbers
+      - [DSR, DTR]
+      - [4, DCD]         # mixed: pin number + label
+
+cables:
+  W1:
+    wirecount: 3
+    colors: [BK, RD, GN]
+
+connections:
+  -
+    - X1: [RX, TX, GND]  # labels in connections too
+    - W1: [1-3]
diff --git a/src/wireviz/DataClasses.py b/src/wireviz/DataClasses.py
index 11e4cf7..467e9f8 100644
--- a/src/wireviz/DataClasses.py
+++ b/src/wireviz/DataClasses.py
@@ -227,8 +227,22 @@ class Connector:
     def resolve_pin(self, pin: Pin) -> Pin:
         """Resolve a pin identifier to its canonical pin number.
 
-        Accepts pin numbers (from self.pins) or pin labels (from
-        self.pinlabels). Raises if ambiguous or not found.
+        Given a value that may be either a pin number (from self.pins)
+        or a pin label (from self.pinlabels), returns the corresponding
+        pin number from self.pins.
+
+        Callers needing a positional index should use
+        self.pins.index(return_value).
+
+        Resolution order:
+            1. Value in both pins and pinlabels at the same position
+               -> return directly (no ambiguity).
+            2. Value in both at different positions -> raise.
+            3. Value only in pinlabels -> return corresponding pin number.
+            4. Value only in pins -> return directly.
+            5. Not found -> raise.
+
+        Note: Lookups are type-sensitive (int 1 != str "1").
         """
         in_pins = pin in self.pins
         in_labels = pin in self.pinlabels if self.pinlabels else False