Add type aliases that reflect their semantics

Using Any or str in type annotations might increase the need for extra
comments to explain the real valid values. However, such needs can be
drastically reduced with the help of semanticly named type aliases.

Each type alias have their legal values described in comments.
Actual validation might be implemented in the future.

src/wireviz/DataClasses.py

@@ -1,29 +1,46 @@
 #!/usr/bin/env python3
 # -*- coding: utf-8 -*-
 
-from typing import Optional, List, Any, Union
+from typing import Optional, List, Tuple, Union
 from dataclasses import dataclass, field, InitVar
 from pathlib import Path
 from wireviz.wv_helper import int2tuple, aspect_ratio
 from wireviz import wv_colors
 
+
+# Each type alias have their legal values described in comments - validation might be implemented in the future
+PlainText = str # Text not containing HTML tags nor newlines
+Hypertext = str # Text possibly including HTML hyperlinks that are removed in all outputs except HTML output
+MultilineHypertext = str # Hypertext possibly also including newlines to break lines in diagram output
+Designator = PlainText # Case insensitive unique name of connector or cable
+
 # Literal type aliases below are commented to avoid requiring python 3.8
-ConnectorMultiplier = str # = Literal['pincount', 'populated']
-CableMultiplier = str # = Literal['wirecount', 'terminations', 'length', 'total_length']
+ConnectorMultiplier = PlainText # = Literal['pincount', 'populated']
+CableMultiplier = PlainText # = Literal['wirecount', 'terminations', 'length', 'total_length']
+ImageScale = PlainText # = Literal['false', 'true', 'width', 'height', 'both']
+Color = PlainText # Two-letter color name = Literal[wv_colors._color_hex.keys()]
+ColorScheme = PlainText # Color scheme name = Literal[wv_colors.COLOR_CODES.keys()]
+
+# Type combinations
+Colors = PlainText # One or more two-letter color names (Color) concatenated into one string
+Pin = Union[int, PlainText] # Pin identifier
+Wire = Union[int, PlainText] # Wire number or Literal['s'] for shield
+NoneOrMorePins = Union[Pin, Tuple[Pin, ...], None] # None, one, or a tuple of pins
+OneOrMoreWires = Union[Wire, Tuple[Wire, ...]] # One or a tuple of wires
 
 
 @dataclass
 class Image:
  gv_dir: InitVar[Path] # Directory of .gv file injected as context during parsing
  # Attributes of the image object <img>:
  src: str
- scale: Optional[str] = None # false | true | width | height | both
+ scale: Optional[ImageScale] = None
  # Attributes of the image cell <td> containing the image:
  width: Optional[int] = None
  height: Optional[int] = None
  fixedsize: Optional[bool] = None
  # Contents of the text cell <td> just below the image cell:
- caption: Optional[str] = None
+ caption: Optional[MultilineHypertext] = None
  # See also HTML doc at https://graphviz.org/doc/info/shapes.html#html
 
  def __post_init__(self, gv_dir):
@@ -47,13 +64,14 @@ def __post_init__(self, gv_dir):
  if self.width:
  self.height = self.width / aspect_ratio(gv_dir.joinpath(self.src))
 
+
 @dataclass
 class AdditionalComponent:
- type: str
- subtype: Optional[str] = None
- manufacturer: Optional[str] = None
- mpn: Optional[str] = None
- pn: Optional[str] = None
+ type: MultilineHypertext
+ subtype: Optional[MultilineHypertext] = None
+ manufacturer: Optional[MultilineHypertext] = None
+ mpn: Optional[MultilineHypertext] = None
+ pn: Optional[Hypertext] = None
  qty: float = 1
  unit: Optional[str] = None
  qty_multiplier: Union[ConnectorMultiplier, CableMultiplier, None] = None
@@ -65,29 +83,29 @@ def description(self) -> str:
 
 @dataclass
 class Connector:
- name: str
- manufacturer: Optional[str] = None
- mpn: Optional[str] = None
- pn: Optional[str] = None
+ name: Designator
+ manufacturer: Optional[MultilineHypertext] = None
+ mpn: Optional[MultilineHypertext] = None
+ pn: Optional[Hypertext] = None
  style: Optional[str] = None
  category: Optional[str] = None
- type: Optional[str] = None
- subtype: Optional[str] = None
+ type: Optional[MultilineHypertext] = None
+ subtype: Optional[MultilineHypertext] = None
  pincount: Optional[int] = None
  image: Optional[Image] = None
- notes: Optional[str] = None
- pinlabels: List[Any] = field(default_factory=list)
- pins: List[Any] = field(default_factory=list)
- color: Optional[str] = None
+ notes: Optional[MultilineHypertext] = None
+ pinlabels: List[Pin] = field(default_factory=list)
+ pins: List[Pin] = field(default_factory=list)
+ color: Optional[Color] = None
  show_name: Optional[bool] = None
  show_pincount: Optional[bool] = None
  hide_disconnected_pins: bool = False
  autogenerate: bool = False
- loops: List[Any] = field(default_factory=list)
+ loops: List[List[Pin]] = field(default_factory=list)
  ignore_in_bom: bool = False
  additional_components: List[AdditionalComponent] = field(default_factory=list)
 
- def __post_init__(self):
+ def __post_init__(self) -> None:
 
  if isinstance(self.image, dict):
  self.image = Image(**self.image)
@@ -139,7 +157,7 @@ def __post_init__(self):
  if isinstance(item, dict):
  self.additional_components[i] = AdditionalComponent(**item)
 
- def activate_pin(self, pin):
+ def activate_pin(self, pin: Pin) -> None:
  self.visible_pins[pin] = True
 
  def get_qty_multiplier(self, qty_multiplier: Optional[ConnectorMultiplier]) -> int:
@@ -155,29 +173,29 @@ def get_qty_multiplier(self, qty_multiplier: Optional[ConnectorMultiplier]) -> i
 
 @dataclass
 class Cable:
- name: str
- manufacturer: Optional[Union[str, List[str]]] = None
- mpn: Optional[Union[str, List[str]]] = None
- pn: Optional[Union[str, List[str]]] = None
+ name: Designator
+ manufacturer: Union[MultilineHypertext, List[MultilineHypertext], None] = None
+ mpn: Union[MultilineHypertext, List[MultilineHypertext], None] = None
+ pn: Union[Hypertext, List[Hypertext], None] = None
  category: Optional[str] = None
- type: Optional[str] = None
+ type: Optional[MultilineHypertext] = None
  gauge: Optional[float] = None
  gauge_unit: Optional[str] = None
  show_equiv: bool = False
  length: float = 0
- color: Optional[str] = None
+ color: Optional[Color] = None
  wirecount: Optional[int] = None
- shield: Union[bool, str] = False # False | True | color
+ shield: Union[bool, Color] = False
  image: Optional[Image] = None
- notes: Optional[str] = None
- colors: List[Any] = field(default_factory=list)
- color_code: Optional[str] = None
+ notes: Optional[MultilineHypertext] = None
+ colors: List[Colors] = field(default_factory=list)
+ color_code: Optional[ColorScheme] = None
  show_name: bool = True
  show_wirecount: bool = True
  ignore_in_bom: bool = False
  additional_components: List[AdditionalComponent] = field(default_factory=list)
 
- def __post_init__(self):
+ def __post_init__(self) -> None:
 
  if isinstance(self.image, dict):
  self.image = Image(**self.image)
@@ -237,7 +255,9 @@ def __post_init__(self):
  if isinstance(item, dict):
  self.additional_components[i] = AdditionalComponent(**item)
 
- def connect(self, from_name, from_pin, via_pin, to_name, to_pin):
+ # The *_pin arguments accept a tuple, but it seems not in use with the current code.
+ def connect(self, from_name: Optional[Designator], from_pin: NoneOrMorePins, via_pin: OneOrMoreWires,
+ to_name: Optional[Designator], to_pin: NoneOrMorePins) -> None:
  from_pin = int2tuple(from_pin)
  via_pin = int2tuple(via_pin)
  to_pin = int2tuple(to_pin)
@@ -264,8 +284,8 @@ def get_qty_multiplier(self, qty_multiplier: Optional[CableMultiplier]) -> float
 
 @dataclass
 class Connection:
- from_name: Any
- from_port: Any
- via_port: Any
- to_name: Any
- to_port: Any
+ from_name: Optional[Designator]
+ from_port: Optional[Pin]
+ via_port: Wire
+ to_name: Optional[Designator]
+ to_port: Optional[Pin]