feat: loop use object to provide more attributes

Author: laurierloi

docs/syntax.md

@@ -81,8 +81,14 @@ options:  # dictionary of common attributes for the whole harness
   hide_disconnected_pins: <bool>  # defaults to false
 
   # loops
-  loops: <List>  # every list item is itself a list of exactly two pins
+  loops: <List[loop]>  # every list item is a loop object representing two pins
                  # on the connector that are to be shorted
+	  loop:
+		- <first>: the first <pin> of the loop
+		- <second>: the second <pin> of the loop
+		- <side>: either "LEFT" or "RIGHT"
+		- show_label: <bool> defaults to true, will show the loop label
+
 ```
 
 ## Cable attributes

examples/ex11.yml

@@ -0,0 +1,52 @@
+# Example 11: loopback wires
+connectors:
+  X1:
+    type: Stewart Connector SS-37000-002
+    subtype: male
+    pinlabels: [DA+,DA-,LB4,LB3,DD+,DD-,LB1, LB2] # pincount is implicit in pinout
+    loops:
+      - first: 1
+        second: 2
+        side: LEFT
+      - first: LB3
+        second: LB4
+        side: LEFT
+  X2:
+    type: Stewart Connector SS-37000-002
+    subtype: male
+    pinlabels: [LB5,LB6,DA+,DD+,DD-,DA-,LB7,LB8]
+    loops:
+      - first: 1
+        second: 2
+        side: RIGHT
+        show_label: false
+      - first: LB7
+        second: LB8
+        side: LEFT
+
+cables:
+  W1:
+    color_code: T568A # auto-color wires based on a standard
+    wirecount: 4 # need to specify number of wires explicitly when using a color code
+    gauge: 24 AWG # also accepts AWG as unit
+    length: 1 # length in m
+    shield: false
+    type: CAT5e
+
+      #WLB1:
+      #  wirecount: 1
+
+      #WLB2:
+      #  wirecount: 1
+
+
+connections:
+  - - X1: [1,2,5,6]
+    - W1: [1-4]
+    - X2: [3,6,4,5] # crossover
+      #- - X1: [7]
+      #  - WLB1: [1]
+      #  - X1: [8]
+      #- - X2: [8]
+      #  - WLB2: [1]
+      #  - X2: [7]

examples/readme.md

@@ -60,3 +60,9 @@
 [Source](ex10.yml) - [Bill of Materials](ex10.bom.tsv)
 
 
+## Example 11
+![](ex11.png)
+
+[Source](ex11.yml) - [Bill of Materials](ex11.bom.tsv)
+
+

src/wireviz/__init__.py

@@ -1,7 +1,7 @@
 # -*- coding: utf-8 -*-
 # Please don't import anything in this file to avoid issues when it is imported in setup.py
 
-__version__ = "0.5.3"
+__version__ = "0.5.4"
 
 CMD_NAME = "wireviz"  # Lower case command and module name
 APP_NAME = "WireViz"  # Application name in texts meant to be human readable

src/wireviz/wv_dataclasses.py

@@ -210,12 +210,32 @@ def __post_init__(self):
 
         self.designator = remove_links(self.designator)
 
+@dataclass
+class Loop():
+    first: PinClass = None
+    second: PinClass = None
+    side: Side = None
+    show_label: bool = True
+
+    def __post_init__(self):
+        if self.side.upper() == 'LEFT':
+            self.side = Side.LEFT
+        elif self.side.upper() == 'RIGHT':
+            self.side = Side.RIGHT
+
+    @property
+    def label(self):
+        if self.show_label:
+            return f'{self.first}<->{self.second}'
+        else:
+            return ''
+
 
 @dataclass
 class Connector(GraphicalComponent):
     # connector-specific properties
     style: Optional[str] = None
-    loops: List[List[Pin]] = field(default_factory=list)
+    loops: List[Loop] = field(default_factory=list)
     # pin information in particular
     pincount: Optional[int] = None
     pins: List[Pin] = field(default_factory=list)  # legacy
@@ -308,6 +328,7 @@ def to_int_pin(pin):
                 return pin
         self.pins = [to_int_pin(p) for p in self.pins]
 
+
         # all checks have passed
         pin_tuples = zip_longest(
             self.pins,
@@ -332,17 +353,41 @@ def to_int_pin(pin):
             # hide pincount for simple (1 pin) connectors by default
             self.show_pincount = self.style != "simple"
 
-        self.loops = [[to_int_pin(p) for p in loop] for loop in self.loops]
+        def get_pin_object(value):
+            pin_id = None
+            if value in self.pinlabels:
+                pin_id = self.pins[self.pinlabels.index(value)]
+            else:
+                err = f'{value} not found in {self.pinlabels}'
+                try:
+                    value = int(value)
+                except ValueError as exc:
+                    raise ValueError(f'{err} and is not an int')
+
+                if value in self.pins:
+                    pin_id = value
+
+            if pin_id is not None:
+                return self.pin_objects[pin_id]
+
+            raise ValueError(f'{err} and is not one of the pins {self.pins}')
+
+        self.loops = [Loop(
+            first=get_pin_object(loop['first']),
+            second=get_pin_object(loop['second']),
+            side=loop.get('side'),
+            show_label=loop.get('show_label', True),
+        ) for loop in self.loops]
+
+
+        #self.loops = [[to_int_pin(p) for p in loop] for loop in self.loops]
         for loop in self.loops:
             # TODO: check that pins to connect actually exist
             # TODO: allow using pin labels in addition to pin numbers,
             #       just like when defining regular connections
             # TODO: include properties of wire used to create the loop
-            if len(loop) != 2:
-                raise Exception("Loops must be between exactly two pins!")
-            # side=None, determine side to show loops during rendering
-            self.activate_pin(loop[0], side=None, is_connection=True)
-            self.activate_pin(loop[1], side=None, is_connection=True)
+            self.activate_pin(loop.first.id, side=loop.side, is_connection=True)
+            self.activate_pin(loop.second.id, side=loop.side, is_connection=True)
 
     def activate_pin(self, pin_id, side: Side = None, is_connection=True) -> None:
         if is_connection:

src/wireviz/wv_graphviz.py

@@ -5,7 +5,7 @@
 
 from wireviz import APP_NAME, APP_URL, __version__
 from wireviz.wv_colors import MultiColor, SingleColor
-from wireviz.wv_dataclasses import Cable, Component, Connector, ShieldClass, WireClass
+from wireviz.wv_dataclasses import Cable, Component, Connector, ShieldClass, WireClass, Side
 from wireviz.wv_html import Img, Table, Td, Tr
 from wireviz.wv_templates import get_template
 from wireviz.wv_utils import html_line_breaks, remove_links
@@ -45,9 +45,18 @@ def gv_connector_loops(connector: Connector) -> List:
     else:
         raise Exception("No side for loops")
     for loop in connector.loops:
-        head = f"{connector.designator}:p{loop[0]}{loop_side}:{loop_dir}"
-        tail = f"{connector.designator}:p{loop[1]}{loop_side}:{loop_dir}"
-        loop_edges.append((head, tail))
+        this_loop_side = loop_side
+        this_loop_dir = loop_dir
+        if loop.side == Side.RIGHT:
+            this_loop_side = 'r'
+            this_loop_dir = 'e'
+        elif loop.side == Side.LEFT:
+            this_loop_side = 'l'
+            this_loop_dir = 'w'
+
+        head = f"{connector.designator}:p{loop.first.id}{this_loop_side}:{this_loop_dir}"
+        tail = f"{connector.designator}:p{loop.second.id}{this_loop_side}:{this_loop_dir}"
+        loop_edges.append((loop, head, tail))
     return loop_edges
 
 

src/wireviz/wv_harness.py

@@ -317,8 +317,8 @@ def create_graph(self) -> Graph:
             if len(connector.loops) > 0:
                 dot.attr("edge", color="#000000")
                 loops = gv_connector_loops(connector)
-                for head, tail in loops:
-                    dot.edge(head, tail)
+                for loop, head, tail in loops:
+                    dot.edge(head, tail, xlabel=loop.label)
 
         # determine if there are double- or triple-colored wires in the harness;
         # if so, pad single-color wires to make all wires of equal thickness