From 537d2484a93d905f6bcbd5af25c79b68f5b9dacb Mon Sep 17 00:00:00 2001 From: KV Date: Sun, 6 Sep 2020 20:58:03 +0200 Subject: [PATCH] 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. --- src/wireviz/DataClasses.py | 73 +++++++++++++++++++++----------------- 1 file changed, 41 insertions(+), 32 deletions(-) diff --git a/src/wireviz/DataClasses.py b/src/wireviz/DataClasses.py index 529ad308..d46dcb1d 100644 --- a/src/wireviz/DataClasses.py +++ b/src/wireviz/DataClasses.py @@ -1,7 +1,7 @@ #!/usr/bin/env python3 # -*- coding: utf-8 -*- -from typing import Optional, List, Any, Union +from typing import Optional, List, Union from dataclasses import dataclass, field, InitVar from pathlib import Path from wireviz.wv_helper import int2tuple, aspect_ratio @@ -10,6 +10,15 @@ # 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'] +ImageScale = str # = Literal['false', 'true', 'width', 'height', 'both'] + +Designator = str # Case insensitive unique name of connector or cable +Pin = Union[int, str] # Pin identifier +Wire = Union[int, str] # Wire number or 's' for shield +MLstr = str # Multi-line string where any newline is properly handled +Color = str # Two-letter color name = Literal[wv_colors._color_hex.keys()] +Colors = str # One or more two-letter color names (Color) concatenated into one string +ColorScheme = str # Color scheme name = Literal[wv_colors.COLOR_CODES.keys()] @dataclass @@ -17,13 +26,13 @@ class Image: gv_dir: InitVar[Path] # Directory of .gv file injected as context during parsing # Attributes of the image object : src: str - scale: Optional[str] = None # false | true | width | height | both + scale: Optional[ImageScale] = None # Attributes of the image cell containing the image: width: Optional[int] = None height: Optional[int] = None fixedsize: Optional[bool] = None # Contents of the text cell just below the image cell: - caption: Optional[str] = None + caption: Optional[MLstr] = None # See also HTML doc at https://graphviz.org/doc/info/shapes.html#html def __post_init__(self, gv_dir): @@ -49,10 +58,10 @@ def __post_init__(self, gv_dir): @dataclass class AdditionalComponent: - type: str - subtype: Optional[str] = None - manufacturer: Optional[str] = None - mpn: Optional[str] = None + type: MLstr + subtype: Optional[MLstr] = None + manufacturer: Optional[MLstr] = None + mpn: Optional[MLstr] = None pn: Optional[str] = None qty: float = 1 unit: Optional[str] = None @@ -65,25 +74,25 @@ def description(self) -> str: @dataclass class Connector: - name: str - manufacturer: Optional[str] = None - mpn: Optional[str] = None + name: Designator + manufacturer: Optional[MLstr] = None + mpn: Optional[MLstr] = None pn: Optional[str] = None style: Optional[str] = None category: Optional[str] = None - type: Optional[str] = None - subtype: Optional[str] = None + type: Optional[MLstr] = None + subtype: Optional[MLstr] = 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[MLstr] = 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) @@ -155,23 +164,23 @@ 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[MLstr, List[MLstr], None] = None + mpn: Union[MLstr, List[MLstr], None] = None + pn: Union[str, List[str], None] = None category: Optional[str] = None - type: Optional[str] = None + type: Optional[MLstr] = 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[MLstr] = 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 @@ -264,8 +273,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]