diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md index a0b3a0e7..09c9e061 100644 --- a/docs/CONTRIBUTING.md +++ b/docs/CONTRIBUTING.md @@ -25,6 +25,7 @@ When contributing to this repository, please [submit a new issue](https://github 1. Create a new feature branch on top of the `dev` branch. 1. Commit your code changes to this feature branch. 1. Push the changes to your fork. +1. Please format your code using [`isort`](https://pycqa.github.io/isort/) and [`black`](https://black.readthedocs.io) before submitting. 1. Submit a new pull request, using `dev` as the base branch. - If your code changes or extends the WireViz YAML syntax, be sure to update the [syntax description document](https://github.com/formatc1702/WireViz/blob/dev/docs/syntax.md) in your PR. 1. Please include in the PR description (and optionally also in the commit message body) a reference (# followed by issue number) to the issue where the suggested changes are discussed. diff --git a/docs/README.md b/docs/README.md index ad2e4aa3..8045f85d 100644 --- a/docs/README.md +++ b/docs/README.md @@ -4,6 +4,7 @@ [![PyPI - Version](https://img.shields.io/pypi/v/wireviz.svg?colorB=blue)](https://pypi.org/project/wireviz/) [![PyPI - Python Version](https://img.shields.io/pypi/pyversions/wireviz.svg?)](https://pypi.org/project/wireviz/) [![PyPI - Downloads](https://img.shields.io/pypi/dm/wireviz)](https://pypi.org/project/wireviz/) +[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black) ## Summary @@ -81,10 +82,11 @@ Output file: [Source](../examples/demo02.yml) - [Bill of Materials](../examples/demo02.bom.tsv) -### Tutorial and example gallery +### Syntax, tutorial and example gallery -See the [tutorial page](../tutorial/readme.md) for sample code, -as well as the [example gallery](../examples/readme.md) to see more of what WireViz can do. +Read the [syntax description](syntax.md) to learn about WireViz' features and how to use them. + +See the [tutorial page](../tutorial/readme.md) for sample code, as well as the [example gallery](../examples/readme.md) to see more of what WireViz can do. ## Usage @@ -125,7 +127,7 @@ If you would like to contribute to this project, make sure you read the [contrib $ wireviz ~/path/to/file/mywire.yml ``` -This will output the following files +Depending on the options specified, this will output some or all of the following files: ``` mywire.gv GraphViz output @@ -135,17 +137,16 @@ mywire.bom.tsv BOM (bill of materials) as tab-separated text file mywire.html HTML page with wiring diagram and BOM embedded ``` -#### Command line options - -- `--prepend-file ` to prepend an additional YAML file. Useful for part libraries and templates shared among multiple cables/harnesses. -- `-o ` or `--output_file ` to generate output files with a name different from the input file. -- `-V` or `--version` to display the WireViz version. -- `-h` or `--help` to see a summary of the usage help text. - +Wildcars in the file path are also supported to process multiple files at once, e.g.: +``` +$ wireviz ~/path/to/files/*.yml +``` -### Syntax description +To see how to specify the output formats, as well as additional options, run: -A description of the WireViz YAML input syntax can be found [here](syntax.md). +``` +$ wireviz --help +``` ### (Re-)Building the example projects diff --git a/docs/syntax.md b/docs/syntax.md index 8da04aee..1c14d3e8 100644 --- a/docs/syntax.md +++ b/docs/syntax.md @@ -85,22 +85,8 @@ tweak: # optional tweaking of .gv output # loops loops: # every list item is itself a list of exactly two pins # on the connector that are to be shorted - - # auto-generation - autogenerate: # optional; defaults to false; see below - ``` -### Auto-generation of connectors - -The `autogenerate: true` option is especially useful for very simple, recurring connectors such as crimp ferrules, splices, and others, where it would be a hassle to individually assign unique designators for every instance. - -By default, when defining a connector, it will be generated once using the specified designator, and can be referenced multiple times, in different connection sets (see below). - -If `autogenerate: true` is set, the connector will _not_ be generated at first. When defining the `connections` section (see below), every time the connector is mentioned, a new instance with an auto-incremented designator is generated and attached. - -Since the auto-incremented and auto-assigned designator is not known to the user, one instance of the connector can not be referenced again outside the point of creation. The `autogenerate: true` option is therefore only useful for terminals with only one wire attached, or splices with exactly one wire going in, and one wire going out. If more wires are to be attached (e.g. for a three-way splice, or a crimp where multiple wires are joined), a separate connector with `autogenerate: false` and a user-defined, unique designator needs to be used. - ## Cable attributes ```yaml @@ -173,6 +159,7 @@ connections: - # Each list entry is a connection set - # Each connection set is itself a list of items - # Items must alternatingly belong to the connectors and cables sections + # Arrows may be used instead of cables -... - # example (single connection) @@ -189,6 +176,18 @@ connections: - [, ..., ] # specify multiple simple connectors to attach in parallel # these may be unique, auto-generated, or a mix of both + - # example (arrows between pins) + - : [, ..., ] + - [, ..., ] # draw arrow linking pins of both connectors + # use single line arrows (--, <--, <-->, -->) + - : [, ..., ] + + - # example (arrows between connectors) + - + - # draw arrow linking the connectors themselves + # use double line arrow (==, <==, <==>, ==>) + - + ... ``` @@ -199,6 +198,7 @@ connections: - When a connection set defines multiple parallel connections, the number of specified ``s and ``s for each component in the set must match. When specifying only one designator, one is auto-generated for each connection of the set. - `` may reference a pin's unique ID (as per the connector's `pins` attribute, auto-numbered from 1 by default) or its label (as per `pinlabels`). - `` may reference a wire's number within a cable/bundle, its label (as per `wirelabels`) or, if unambiguous, its color. +- For ``, see below. ### Single connections @@ -249,6 +249,80 @@ For connectors with `autogenerate: true`, a new instance, with auto-generated de - `-` auto-expands to a range. - `` to refer to a wire's label or color, if unambiguous. +### Arrows + +Arrows may be used in place of wires to join two connectors. This can represent the mating of matching connectors. + +To represent joining individual pins between two connectors, a list of single arrows is used: +```yaml +connections: + - + - : [,...,] + - [, ..., ] # --, <--, <--> or --> + - : [,...,] +``` + +To represent mating of two connectors as a whole, one double arrow is used: +```yaml +connections: + - + - # using connector designator only + - # ==, <==, <==> or ==> + - + - + - ... + - : [, ...] # designator and pinlist (pinlist is ignored) + # useful when combining arrows and wires + - # ==, <==, <==> or ==> + - : [, ...] + - ... +``` + +### Autogeneration of items + +For very simple, recurring connectors such as crimp ferrules, splices and others, where it would be a hassle to individually assign unique designators for every instance, autogeneration may be used. Both connectors and cables can be autogenerated. + +Example (see `connections` section): + +```yaml +connectors: + X: + # ... + Y: + # ... + Z: + style: simple + # ... +cables: + V: + # ... + W: + # ... + +connections: + - # no autogeneration (normal use) + - X: [1,2,...] # Use X as both the template and the instance designator + - V: [1,2,...] # Use V as both the template and the instance designator + # ... + + - # autogeneration of named instances + - Y.Y1: [1,2,...] # Use template Y, generate instance with designator Y1 + - W.W1: [1,2,...] # Use template W, generate instance with designator W1 + - Y.Y2: [1,2,...] # generate more instances from the same templates + - W.W2: [1,2,...] + - Y.Y3: [1,2,...] + + - # autogeneration of unnamed instances + - Y3: [1,2,...] # reuse existing instance Y3 + - W.W4: [1,2,...] + - Z. # Use template Z, generate one unnamed instance + # for each connection in set +``` + +Since the internally assigned designator of an unnamed component is not known to the user, one instance of the connector can not be referenced again outside the point of creation (i.e. in other connection sets, or later in the same set). Autogeneration of unnamed instances is therefore only useful for terminals with only one wire attached, or splices with exactly one wire going in, and one wire going out. +If a component is to be used in other connection sets (e.g. for a three-way splice, or a crimp where multiple wires are joined), a named instance needs to be used. + +Names of autogenerated components are hidden by default. While they can be shown in the graphical output using the `show_name: true` option, it is not recommended to manually use the internally assigned designator (starting with a double underscore `__`), since it might change in future WireViz versions, or when the order of items in connection sets changes. ## Metadata entries @@ -300,6 +374,7 @@ For connectors with `autogenerate: true`, a new instance, with auto-generated de mini_bom_mode: # Default = True ``` + ## BOM items and additional components Connectors (both regular, and auto-generated), cables, and wires of a bundle are automatically added to the BOM, diff --git a/examples/demo02.yml b/examples/demo02.yml index 5002e7d2..5e94df7f 100644 --- a/examples/demo02.yml +++ b/examples/demo02.yml @@ -1,3 +1,26 @@ +metadata: + + title: WireViz Demo 2 + pn: WV-DEMO-02 + + authors: + Created: + name: D. Rojas + date: 2020-05-20 + Approved: + name: D. Rojas + date: 2020-05-20 + + revisions: + A: + name: D. Rojas + date: 2020-10-17 + changelog: WireViz 0.2 release + + template: + name: din-6771 + sheetsize: A3 + templates: # defining templates to be used later on - &molex_f type: Molex KK 254 @@ -22,9 +45,8 @@ connectors: X4: <<: *molex_f pinlabels: [GND, +12V, MISO, MOSI, SCK] - ferrule_crimp: + F: style: simple - autogenerate: true type: Crimp ferrule subtype: 0.25 mm² color: YE @@ -64,6 +86,6 @@ connections: - W3: [1-4] - X4: [1,3-5] - - - ferrule_crimp + - F. - W4: [1,2] - X4: [1,2] diff --git a/examples/ex04.yml b/examples/ex04.yml index 74148ecf..c3c7234e 100644 --- a/examples/ex04.yml +++ b/examples/ex04.yml @@ -8,13 +8,12 @@ cables: category: bundle connectors: - ferrule_crimp: + F: style: simple - autogenerate: true type: Crimp ferrule connections: - - - ferrule_crimp + - F. - W1: [1-6] - - ferrule_crimp + - F. diff --git a/examples/ex11.yml b/examples/ex11.yml new file mode 100644 index 00000000..0d88a64b --- /dev/null +++ b/examples/ex11.yml @@ -0,0 +1,25 @@ +# based on @stmaxed's example in #134 + +connectors: + X1: &X + type: Screw connector + subtype: male + color: GN + pincount: 4 + pinlabels: [A, B, C, D] + F: + style: simple + type: Ferrule + color: GY + +cables: + W: + color: BK + colors: [BK, WH, BU, BN] + +connections: + - # ferrules + connector X1 + - W.W1: [1-4] + - F. + - --> + - X1: [1-4] diff --git a/examples/ex12.yml b/examples/ex12.yml new file mode 100644 index 00000000..a8a4c85c --- /dev/null +++ b/examples/ex12.yml @@ -0,0 +1,25 @@ +# based on @MSBGit's example in #134 + +connectors: + X1: &dupont + type: Dupont 2.54mm + subtype: male + pincount: 5 + color: BK + X2: + <<: *dupont + subtype: female + +cables: + W: + category: bundle + colors: [RD, BK, BU, GN] + length: 0.2 + +connections: + - + - W.W1: [1-4] + - X1: [1-4] + - ==> + - X2: [1-4] + - W.W2: [1-4] diff --git a/examples/ex13.yml b/examples/ex13.yml new file mode 100644 index 00000000..85b90814 --- /dev/null +++ b/examples/ex13.yml @@ -0,0 +1,26 @@ +# based on @formatc1702's example in #184 + +connectors: + X: + pincount: 4 + pinlabels: [A, B, C, D] + F: + style: simple + type: ferrule + +cables: + C: + wirecount: 4 + color_code: DIN + +connections: + - + - X.X1: [1-4] + - C.C1: [1-4] + - [F.F1, F.F2, F.F3, F.F4] # generate new instances of F and assign designators + - C.C2: [1-4] + - X.X2: [1-4] + - + - [F1, F2, F3, F4] # use previously assigned designators + - C.C3: [1-4] + - X.X3: [1-4] diff --git a/examples/ex14.yml b/examples/ex14.yml new file mode 100644 index 00000000..bad0256f --- /dev/null +++ b/examples/ex14.yml @@ -0,0 +1,55 @@ +connectors: + JSTMALE: &JST_SM # use generic names here, assign designators at generation time + type: JST SM + subtype: male + pincount: 4 + pinlabels: [A, B, C, D] + JSTFEMALE: + <<: *JST_SM # easily create JSTMALE's matching connector + subtype: female + X4: # this connector is only used once, use fixed designator here already + type: Screw terminal connector + pincount: 4 + color: GN + pinlabels: [W, X, Y, Z] + S: + style: simple + type: Splice + color: CU + F: + style: simple + type: Ferrule + color: GY + + +cables: + CABLE: + wirecount: 4 + color_code: DIN + length: 0.1 + WIRE: + wirecount: 1 + colors: [BK] + length: 0.1 + +connections: + - + - JSTMALE.X1: [4-1] # use `.` syntax to generate a new instance of JSTMALE, named X1 + - CABLE.W1: [1-4] # same syntax for cables + - [S., S., S.S1, S.] # splice W1 and W2 together; only wire #3 needs a user-defined designator + - CABLE.W2: [1-4] + - S. # test shorthand, auto-get required number of ferrules from context + - CABLE.W21: [1-4] + - JSTFEMALE.X2: [1-4] + - <=> # mate X2 and X3 + - JSTMALE.X3: [1-4] + - CABLE.W3: [1-4] + - [F., F., F., F.] + - --> # insert ferrules into screw terminal connector + - X4: [2,1,4,3] # X4 does not require auto-generation, thus no `.` syntax here + - + - S1: [1] # reuse previously generated splice + # TODO: Make it work with `- F1` only, making pin 1 is implied + - WIRE.: [1] # We don't care about a simple wire's designator, auto-generate please! + # TODO: Make it work with `- W.W4: 1`, dropping the need for `[]` + - X2: [4] diff --git a/pyproject.toml b/pyproject.toml new file mode 100644 index 00000000..5d7bf33d --- /dev/null +++ b/pyproject.toml @@ -0,0 +1,2 @@ +[tool.isort] +profile = "black" diff --git a/requirements.txt b/requirements.txt index 36f048c4..07564c32 100644 --- a/requirements.txt +++ b/requirements.txt @@ -1,3 +1,4 @@ +click graphviz pillow pyyaml diff --git a/setup.py b/setup.py index 4992bc56..8cdd4864 100644 --- a/setup.py +++ b/setup.py @@ -1,47 +1,45 @@ #!/usr/bin/env python3 # -*- coding: utf-8 -*- -import os -from setuptools import setup, find_packages +from pathlib import Path -from src.wireviz import __version__, CMD_NAME, APP_URL +from setuptools import find_packages, setup -# Utility function to read the README file. -# Used for the long_description. It's nice, because now 1) we have a top level -# README file and 2) it's easier to type in the README file than to put a raw -# string in below ... -def read(fname): - return open(os.path.join(os.path.dirname(__file__), fname)).read() +from src.wireviz import APP_URL, CMD_NAME, __version__ + +README_PATH = Path(__file__).parent / "docs" / "README.md" setup( name=CMD_NAME, version=__version__, - author='Daniel Rojas', - #author_email='', - description='Easily document cables and wiring harnesses', - long_description=read(os.path.join(os.path.dirname(__file__), 'docs/README.md')), - long_description_content_type='text/markdown', + author="Daniel Rojas", + # author_email='', + description="Easily document cables and wiring harnesses", + long_description=open(README_PATH).read(), + long_description_content_type="text/markdown", install_requires=[ - 'pyyaml', - 'pillow', - 'graphviz', - ], - license='GPLv3', - keywords='cable connector hardware harness wiring wiring-diagram wiring-harness', + "click", + "pyyaml", + "pillow", + "graphviz", + ], + license="GPLv3", + keywords="cable connector hardware harness wiring wiring-diagram wiring-harness", url=APP_URL, - package_dir={'': 'src'}, - packages=find_packages('src'), + package_dir={"": "src"}, + packages=find_packages("src"), entry_points={ - 'console_scripts': ['wireviz=wireviz.wireviz:main'], - }, - classifiers=[ - 'Development Status :: 4 - Beta', - 'Environment :: Console', - 'Programming Language :: Python :: 3', - 'Programming Language :: Python :: 3.7', - 'Programming Language :: Python :: 3.8', - 'Topic :: Utilities', - 'License :: OSI Approved :: GNU General Public License v3 (GPLv3)', + "console_scripts": [ + "wireviz=wireviz.wv_cli:wireviz", ], - + }, + classifiers=[ + "Development Status :: 4 - Beta", + "Environment :: Console", + "Programming Language :: Python :: 3", + "Programming Language :: Python :: 3.7", + "Programming Language :: Python :: 3.8", + "Topic :: Utilities", + "License :: OSI Approved :: GNU General Public License v3 (GPLv3)", + ], ) diff --git a/src/wireviz/DataClasses.py b/src/wireviz/DataClasses.py index 6b7462ab..71aa993c 100644 --- a/src/wireviz/DataClasses.py +++ b/src/wireviz/DataClasses.py @@ -1,47 +1,65 @@ # -*- coding: utf-8 -*- -from typing import Dict, List, Optional, Tuple, Union -from dataclasses import dataclass, field, InitVar +from dataclasses import InitVar, dataclass, field +from enum import Enum, auto from pathlib import Path +from typing import Dict, List, Optional, Tuple, Union -from wireviz.wv_helper import int2tuple, aspect_ratio -from wireviz.wv_colors import Color, Colors, ColorMode, ColorScheme, COLOR_CODES - +from wireviz.wv_colors import COLOR_CODES, Color, ColorMode, Colors, ColorScheme +from wireviz.wv_helper import aspect_ratio, int2tuple # 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 +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 = PlainText # = Literal['pincount', 'populated'] -CableMultiplier = PlainText # = Literal['wirecount', 'terminations', 'length', 'total_length'] -ImageScale = PlainText # = Literal['false', 'true', 'width', 'height', 'both'] +ConnectorMultiplier = PlainText # = Literal['pincount', 'populated'] +CableMultiplier = ( + PlainText # = Literal['wirecount', 'terminations', 'length', 'total_length'] +) +ImageScale = PlainText # = Literal['false', 'true', 'width', 'height', 'both'] # Type combinations -Pin = Union[int, PlainText] # Pin identifier -PinIndex = int # Zero-based pin index -Wire = Union[int, PlainText] # Wire number or Literal['s'] for shield -NoneOrMorePinIndices = Union[PinIndex, Tuple[PinIndex, ...], None] # None, one, or a tuple of zero-based pin indices -OneOrMoreWires = Union[Wire, Tuple[Wire, ...]] # One or a tuple of wires +Pin = Union[int, PlainText] # Pin identifier +PinIndex = int # Zero-based pin index +Wire = Union[int, PlainText] # Wire number or Literal['s'] for shield +NoneOrMorePins = Union[ + Pin, Tuple[Pin, ...], None +] # None, one, or a tuple of pin identifiers +NoneOrMorePinIndices = Union[ + PinIndex, Tuple[PinIndex, ...], None +] # None, one, or a tuple of zero-based pin indices +OneOrMoreWires = Union[Wire, Tuple[Wire, ...]] # One or a tuple of wires # Metadata can contain whatever is needed by the HTML generation/template. MetadataKeys = PlainText # Literal['title', 'description', 'notes', ...] + + +class Side(Enum): + LEFT = auto() + RIGHT = auto() + + class Metadata(dict): pass @dataclass class Options: - fontname: PlainText = 'arial' - bgcolor: Color = 'WH' - bgcolor_node: Optional[Color] = 'WH' + fontname: PlainText = "arial" + bgcolor: Color = "WH" + bgcolor_node: Optional[Color] = "WH" bgcolor_connector: Optional[Color] = None bgcolor_cable: Optional[Color] = None bgcolor_bundle: Optional[Color] = None - color_mode: ColorMode = 'SHORT' + color_mode: ColorMode = "SHORT" mini_bom_mode: bool = True + template_separator: str = "." def __post_init__(self): if not self.bgcolor_node: @@ -62,7 +80,6 @@ class Tweak: @dataclass class Image: - gv_dir: InitVar[Path] # Directory of .gv file injected as context during parsing # Attributes of the image object : src: str scale: Optional[ImageScale] = None @@ -75,26 +92,29 @@ class Image: caption: Optional[MultilineHypertext] = None # See also HTML doc at https://graphviz.org/doc/info/shapes.html#html - def __post_init__(self, gv_dir): + def __post_init__(self): if self.fixedsize is None: # Default True if any dimension specified unless self.scale also is specified. self.fixedsize = (self.width or self.height) and self.scale is None if self.scale is None: - self.scale = "false" if not self.width and not self.height \ - else "both" if self.width and self.height \ - else "true" # When only one dimension is specified. + if not self.width and not self.height: + self.scale = "false" + elif self.width and self.height: + self.scale = "both" + else: + self.scale = "true" # When only one dimension is specified. if self.fixedsize: # If only one dimension is specified, compute the other # because Graphviz requires both when fixedsize=True. if self.height: if not self.width: - self.width = self.height * aspect_ratio(gv_dir.joinpath(self.src)) + self.width = self.height * aspect_ratio(self.src) else: if self.width: - self.height = self.width / aspect_ratio(gv_dir.joinpath(self.src)) + self.height = self.width / aspect_ratio(self.src) @dataclass @@ -113,7 +133,8 @@ class AdditionalComponent: @property def description(self) -> str: - return self.type.rstrip() + (f', {self.subtype.rstrip()}' if self.subtype else '') + s = self.type.rstrip() + f", {self.subtype.rstrip()}" if self.subtype else "" + return s @dataclass @@ -140,7 +161,6 @@ class Connector: show_name: Optional[bool] = None show_pincount: Optional[bool] = None hide_disconnected_pins: bool = False - autogenerate: bool = False loops: List[List[Pin]] = field(default_factory=list) ignore_in_bom: bool = False additional_components: List[AdditionalComponent] = field(default_factory=list) @@ -154,52 +174,66 @@ def __post_init__(self) -> None: self.ports_right = False self.visible_pins = {} - if self.style == 'simple': + if self.style == "simple": if self.pincount and self.pincount > 1: - raise Exception('Connectors with style set to simple may only have one pin') + raise Exception( + "Connectors with style set to simple may only have one pin" + ) self.pincount = 1 if not self.pincount: - self.pincount = max(len(self.pins), len(self.pinlabels), len(self.pincolors)) + self.pincount = max( + len(self.pins), len(self.pinlabels), len(self.pincolors) + ) if not self.pincount: - raise Exception('You need to specify at least one, pincount, pins, pinlabels, or pincolors') + raise Exception( + "You need to specify at least one, pincount, pins, pinlabels, or pincolors" + ) # create default list for pins (sequential) if not specified if not self.pins: self.pins = list(range(1, self.pincount + 1)) if len(self.pins) != len(set(self.pins)): - raise Exception('Pins are not unique') + raise Exception("Pins are not unique") if self.show_name is None: - self.show_name = not self.autogenerate # hide auto-generated designators by default + # hide designators for simple and for auto-generated connectors by default + self.show_name = self.style != "simple" and self.name[0:2] != "__" if self.show_pincount is None: - self.show_pincount = self.style != 'simple' # hide pincount for simple (1 pin) connectors by default + # hide pincount for simple (1 pin) connectors by default + self.show_pincount = self.style != "simple" 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!') + raise Exception("Loops must be between exactly two pins!") for i, item in enumerate(self.additional_components): if isinstance(item, dict): self.additional_components[i] = AdditionalComponent(**item) - def activate_pin(self, pin: Pin) -> None: + def activate_pin(self, pin: Pin, side: Side) -> None: self.visible_pins[pin] = True + if side == Side.LEFT: + self.ports_left = True + elif side == Side.RIGHT: + self.ports_right = True def get_qty_multiplier(self, qty_multiplier: Optional[ConnectorMultiplier]) -> int: if not qty_multiplier: return 1 - elif qty_multiplier == 'pincount': + elif qty_multiplier == "pincount": return self.pincount - elif qty_multiplier == 'populated': + elif qty_multiplier == "populated": return sum(self.visible_pins.values()) else: - raise ValueError(f'invalid qty multiplier parameter for connector {qty_multiplier}') + raise ValueError( + f"invalid qty multiplier parameter for connector {qty_multiplier}" + ) @dataclass @@ -227,7 +261,7 @@ class Cable: colors: List[Colors] = field(default_factory=list) wirelabels: List[Wire] = field(default_factory=list) color_code: Optional[ColorScheme] = None - show_name: bool = True + show_name: Optional[bool] = None show_wirecount: bool = True show_wirenumbers: Optional[bool] = None ignore_in_bom: bool = False @@ -240,65 +274,78 @@ def __post_init__(self) -> None: if isinstance(self.gauge, str): # gauge and unit specified try: - g, u = self.gauge.split(' ') + g, u = self.gauge.split(" ") except Exception: - raise Exception(f'Cable {self.name} gauge={self.gauge} - Gauge must be a number, or number and unit separated by a space') + raise Exception( + f"Cable {self.name} gauge={self.gauge} - Gauge must be a number, or number and unit separated by a space" + ) self.gauge = g if self.gauge_unit is not None: - print(f'Warning: Cable {self.name} gauge_unit={self.gauge_unit} is ignored because its gauge contains {u}') - if u.upper() == 'AWG': + print( + f"Warning: Cable {self.name} gauge_unit={self.gauge_unit} is ignored because its gauge contains {u}" + ) + if u.upper() == "AWG": self.gauge_unit = u.upper() else: - self.gauge_unit = u.replace('mm2', 'mm\u00B2') + self.gauge_unit = u.replace("mm2", "mm\u00B2") elif self.gauge is not None: # gauge specified, assume mm2 if self.gauge_unit is None: - self.gauge_unit = 'mm\u00B2' + self.gauge_unit = "mm\u00B2" else: pass # gauge not specified if isinstance(self.length, str): # length and unit specified try: - L, u = self.length.split(' ') + L, u = self.length.split(" ") L = float(L) except Exception: - raise Exception(f'Cable {self.name} length={self.length} - Length must be a number, or number and unit separated by a space') + raise Exception( + f"Cable {self.name} length={self.length} - Length must be a number, or number and unit separated by a space" + ) self.length = L if self.length_unit is not None: - print(f'Warning: Cable {self.name} length_unit={self.length_unit} is ignored because its length contains {u}') + print( + f"Warning: Cable {self.name} length_unit={self.length_unit} is ignored because its length contains {u}" + ) self.length_unit = u elif not any(isinstance(self.length, t) for t in [int, float]): - raise Exception(f'Cable {self.name} length has a non-numeric value') + raise Exception(f"Cable {self.name} length has a non-numeric value") elif self.length_unit is None: - self.length_unit = 'm' + self.length_unit = "m" self.connections = [] if self.wirecount: # number of wires explicitly defined if self.colors: # use custom color palette (partly or looped if needed) pass - elif self.color_code: # use standard color palette (partly or looped if needed) + elif self.color_code: + # use standard color palette (partly or looped if needed) if self.color_code not in COLOR_CODES: - raise Exception('Unknown color code') + raise Exception("Unknown color code") self.colors = COLOR_CODES[self.color_code] else: # no colors defined, add dummy colors - self.colors = [''] * self.wirecount + self.colors = [""] * self.wirecount # make color code loop around if more wires than colors if self.wirecount > len(self.colors): m = self.wirecount // len(self.colors) + 1 self.colors = self.colors * int(m) # cut off excess after looping - self.colors = self.colors[:self.wirecount] + self.colors = self.colors[: self.wirecount] else: # wirecount implicit in length of color list if not self.colors: - raise Exception('Unknown number of wires. Must specify wirecount or colors (implicit length)') + raise Exception( + "Unknown number of wires. Must specify wirecount or colors (implicit length)" + ) self.wirecount = len(self.colors) if self.wirelabels: - if self.shield and 's' in self.wirelabels: - raise Exception('"s" may not be used as a wire label for a shielded cable.') + if self.shield and "s" in self.wirelabels: + raise Exception( + '"s" may not be used as a wire label for a shielded cable.' + ) # if lists of part numbers are provided check this is a bundle and that it matches the wirecount. for idfield in [self.manufacturer, self.mpn, self.supplier, self.spn, self.pn]: @@ -306,48 +353,79 @@ def __post_init__(self) -> None: if self.category == "bundle": # check the length if len(idfield) != self.wirecount: - raise Exception('lists of part data must match wirecount') + raise Exception("lists of part data must match wirecount") else: - raise Exception('lists of part data are only supported for bundles') + raise Exception("lists of part data are only supported for bundles") + + if self.show_name is None: + # hide designators for auto-generated cables by default + self.show_name = self.name[0:2] != "__" - # by default, show wire numbers for cables, hide for bundles - if self.show_wirenumbers is None: - self.show_wirenumbers = self.category != 'bundle' + if not self.show_wirenumbers: + # by default, show wire numbers for cables, hide for bundles + self.show_wirenumbers = self.category != "bundle" for i, item in enumerate(self.additional_components): if isinstance(item, dict): self.additional_components[i] = AdditionalComponent(**item) # 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: NoneOrMorePinIndices, via_wire: OneOrMoreWires, - to_name: Optional[Designator], to_pin: NoneOrMorePinIndices) -> None: + def connect( + self, + from_name: Optional[Designator], + from_pin: NoneOrMorePinIndices, + via_wire: OneOrMoreWires, + to_name: Optional[Designator], + to_pin: NoneOrMorePinIndices, + ) -> None: + from_pin = int2tuple(from_pin) via_wire = int2tuple(via_wire) to_pin = int2tuple(to_pin) if len(from_pin) != len(to_pin): - raise Exception('from_pin must have the same number of elements as to_pin') + raise Exception("from_pin must have the same number of elements as to_pin") for i, _ in enumerate(from_pin): - self.connections.append(Connection(from_name, from_pin[i], via_wire[i], to_name, to_pin[i])) + self.connections.append( + Connection(from_name, from_pin[i], via_wire[i], to_name, to_pin[i]) + ) def get_qty_multiplier(self, qty_multiplier: Optional[CableMultiplier]) -> float: if not qty_multiplier: return 1 - elif qty_multiplier == 'wirecount': + elif qty_multiplier == "wirecount": return self.wirecount - elif qty_multiplier == 'terminations': + elif qty_multiplier == "terminations": return len(self.connections) - elif qty_multiplier == 'length': + elif qty_multiplier == "length": return self.length - elif qty_multiplier == 'total_length': + elif qty_multiplier == "total_length": return self.length * self.wirecount else: - raise ValueError(f'invalid qty multiplier parameter for cable {qty_multiplier}') + raise ValueError( + f"invalid qty multiplier parameter for cable {qty_multiplier}" + ) @dataclass class Connection: from_name: Optional[Designator] - from_port: Optional[PinIndex] + from_pin: Optional[Pin] via_port: Wire to_name: Optional[Designator] - to_port: Optional[PinIndex] + to_pin: Optional[Pin] + + +@dataclass +class MatePin: + from_name: Designator + from_pin: Pin + to_name: Designator + to_pin: Pin + shape: str + + +@dataclass +class MateComponent: + from_name: Designator + to_name: Designator + shape: str diff --git a/src/wireviz/Harness.py b/src/wireviz/Harness.py index 2f9eb641..5acda02c 100644 --- a/src/wireviz/Harness.py +++ b/src/wireviz/Harness.py @@ -1,25 +1,56 @@ # -*- coding: utf-8 -*- -from graphviz import Graph +import re from collections import Counter -from typing import Any, List, Union from dataclasses import dataclass -from pathlib import Path from itertools import zip_longest -import re +from pathlib import Path +from typing import Any, List, Union -from wireviz import wv_colors, __version__, APP_NAME, APP_URL -from wireviz.DataClasses import Metadata, Options, Tweak, Connector, Cable +from graphviz import Graph + +from wireviz import APP_NAME, APP_URL, __version__, wv_colors +from wireviz.DataClasses import ( + Cable, + Connector, + MateComponent, + MatePin, + Metadata, + Options, + Tweak, + Side, +) +from wireviz.wv_bom import ( + HEADER_MPN, + HEADER_PN, + HEADER_SPN, + bom_list, + component_table_entry, + generate_bom, + get_additional_component_table, + pn_info_string, +) from wireviz.wv_colors import get_color_hex, translate_color -from wireviz.wv_gv_html import nested_html_table, \ - html_bgcolor_attr, html_bgcolor, html_colorbar, \ - html_image, html_caption, remove_links, html_line_breaks -from wireviz.wv_bom import pn_info_string, component_table_entry, \ - get_additional_component_table, bom_list, generate_bom, \ - HEADER_PN, HEADER_MPN, HEADER_SPN +from wireviz.wv_gv_html import ( + html_bgcolor, + html_bgcolor_attr, + html_caption, + html_colorbar, + html_image, + html_line_breaks, + nested_html_table, + remove_links, +) +from wireviz.wv_helper import ( + awg_equiv, + flatten2d, + is_arrow, + mm2_equiv, + open_file_read, + open_file_write, + tuplelist2tsv, +) from wireviz.wv_html import generate_html_output -from wireviz.wv_helper import awg_equiv, mm2_equiv, tuplelist2tsv, flatten2d, \ - open_file_read, open_file_write @dataclass @@ -31,6 +62,7 @@ class Harness: def __post_init__(self): self.connectors = {} self.cables = {} + self.mates = [] self._bom = [] # Internal Cache for generated bom self.additional_bom_items = [] @@ -40,10 +72,26 @@ def add_connector(self, name: str, *args, **kwargs) -> None: def add_cable(self, name: str, *args, **kwargs) -> None: self.cables[name] = Cable(name, *args, **kwargs) + def add_mate_pin(self, from_name, from_pin, to_name, to_pin, arrow_type) -> None: + self.mates.append(MatePin(from_name, from_pin, to_name, to_pin, arrow_type)) + self.connectors[from_name].activate_pin(from_pin, Side.RIGHT) + self.connectors[to_name].activate_pin(to_pin, Side.LEFT) + + def add_mate_component(self, from_name, to_name, arrow_type) -> None: + self.mates.append(MateComponent(from_name, to_name, arrow_type)) + def add_bom_item(self, item: dict) -> None: self.additional_bom_items.append(item) - def connect(self, from_name: str, from_pin: (int, str), via_name: str, via_wire: (int, str), to_name: str, to_pin: (int, str)) -> None: + def connect( + self, + from_name: str, + from_pin: (int, str), + via_name: str, + via_wire: (int, str), + to_name: str, + to_pin: (int, str), + ) -> None: # check from and to connectors for (name, pin) in zip([from_name, to_name], [from_pin, to_pin]): if name is not None and name in self.connectors: @@ -51,19 +99,21 @@ def connect(self, from_name: str, from_pin: (int, str), via_name: str, via_wire: # check if provided name is ambiguous if pin in connector.pins and pin in connector.pinlabels: if connector.pins.index(pin) != connector.pinlabels.index(pin): - raise Exception(f'{name}:{pin} is defined both in pinlabels and pins, for different pins.') + raise Exception( + f"{name}:{pin} is defined both in pinlabels and pins, for different pins." + ) # TODO: Maybe issue a warning if present in both lists but referencing the same pin? if pin in connector.pinlabels: if connector.pinlabels.count(pin) > 1: - raise Exception(f'{name}:{pin} is defined more than once.') + raise Exception(f"{name}:{pin} is defined more than once.") index = connector.pinlabels.index(pin) - pin = connector.pins[index] # map pin name to pin number + pin = connector.pins[index] # map pin name to pin number if name == from_name: from_pin = pin if name == to_name: to_pin = pin if not pin in connector.pins: - raise Exception(f'{name}:{pin} not found.') + raise Exception(f"{name}:{pin} not found.") # check via cable if via_name in self.cables: @@ -71,51 +121,56 @@ def connect(self, from_name: str, from_pin: (int, str), via_name: str, via_wire: # check if provided name is ambiguous if via_wire in cable.colors and via_wire in cable.wirelabels: if cable.colors.index(via_wire) != cable.wirelabels.index(via_wire): - raise Exception(f'{via_name}:{via_wire} is defined both in colors and wirelabels, for different wires.') + raise Exception( + f"{via_name}:{via_wire} is defined both in colors and wirelabels, for different wires." + ) # TODO: Maybe issue a warning if present in both lists but referencing the same wire? if via_wire in cable.colors: if cable.colors.count(via_wire) > 1: - raise Exception(f'{via_name}:{via_wire} is used for more than one wire.') - via_wire = cable.colors.index(via_wire) + 1 # list index starts at 0, wire IDs start at 1 + raise Exception( + f"{via_name}:{via_wire} is used for more than one wire." + ) + # list index starts at 0, wire IDs start at 1 + via_wire = cable.colors.index(via_wire) + 1 elif via_wire in cable.wirelabels: if cable.wirelabels.count(via_wire) > 1: - raise Exception(f'{via_name}:{via_wire} is used for more than one wire.') - via_wire = cable.wirelabels.index(via_wire) + 1 # list index starts at 0, wire IDs start at 1 - - from_pin_id = self.connectors[from_name].pins.index(from_pin) if from_pin is not None else None - to_pin_id = self.connectors[to_name].pins.index(to_pin) if to_pin is not None else None - - self.cables[via_name].connect(from_name, from_pin_id, via_wire, to_name, to_pin_id) + raise Exception( + f"{via_name}:{via_wire} is used for more than one wire." + ) + via_wire = ( + cable.wirelabels.index(via_wire) + 1 + ) # list index starts at 0, wire IDs start at 1 + + # perform the actual connection + self.cables[via_name].connect(from_name, from_pin, via_wire, to_name, to_pin) if from_name in self.connectors: - self.connectors[from_name].activate_pin(from_pin) + self.connectors[from_name].activate_pin(from_pin, Side.RIGHT) if to_name in self.connectors: - self.connectors[to_name].activate_pin(to_pin) + self.connectors[to_name].activate_pin(to_pin, Side.LEFT) def create_graph(self) -> Graph: dot = Graph() - dot.body.append(f'// Graph generated by {APP_NAME} {__version__}') - dot.body.append(f'// {APP_URL}') - dot.attr('graph', rankdir='LR', - ranksep='2', - bgcolor=wv_colors.translate_color(self.options.bgcolor, "HEX"), - nodesep='0.33', - fontname=self.options.fontname) - dot.attr('node', - shape='none', - width='0', height='0', margin='0', # Actual size of the node is entirely determined by the label. - style='filled', - fillcolor=wv_colors.translate_color(self.options.bgcolor_node, "HEX"), - fontname=self.options.fontname) - dot.attr('edge', style='bold', - fontname=self.options.fontname) - - # prepare ports on connectors depending on which side they will connect - for _, cable in self.cables.items(): - for connection_color in cable.connections: - if connection_color.from_port is not None: # connect to left - self.connectors[connection_color.from_name].ports_right = True - if connection_color.to_port is not None: # connect to right - self.connectors[connection_color.to_name].ports_left = True + dot.body.append(f"// Graph generated by {APP_NAME} {__version__}") + dot.body.append(f"// {APP_URL}") + dot.attr( + "graph", + rankdir="LR", + ranksep="2", + bgcolor=wv_colors.translate_color(self.options.bgcolor, "HEX"), + nodesep="0.33", + fontname=self.options.fontname, + ) + dot.attr( + "node", + shape="none", + width="0", + height="0", + margin="0", # Actual size of the node is entirely determined by the label. + style="filled", + fillcolor=wv_colors.translate_color(self.options.bgcolor_node, "HEX"), + fontname=self.options.fontname, + ) + dot.attr("edge", style="bold", fontname=self.options.fontname) for connector in self.connectors.values(): @@ -124,7 +179,7 @@ def create_graph(self) -> Graph: connector.ports_left = True # Use left side pins. html = [] - + # fmt: off rows = [[f'{html_bgcolor(connector.bgcolor_title)}{remove_links(connector.name)}' if connector.show_name else None], [pn_info_string(HEADER_PN, None, remove_links(connector.pn)), @@ -138,78 +193,106 @@ def create_graph(self) -> Graph: '' if connector.style != 'simple' else None, [html_image(connector.image)], [html_caption(connector.image)]] + # fmt: on + rows.extend(get_additional_component_table(self, connector)) rows.append([html_line_breaks(connector.notes)]) html.extend(nested_html_table(rows, html_bgcolor_attr(connector.bgcolor))) - if connector.style != 'simple': + if connector.style != "simple": pinhtml = [] - pinhtml.append('') - - for pinindex, (pinname, pinlabel, pincolor) in enumerate(zip_longest(connector.pins, connector.pinlabels, connector.pincolors)): - if connector.hide_disconnected_pins and not connector.visible_pins.get(pinname, False): + pinhtml.append( + '
' + ) + + for pinindex, (pinname, pinlabel, pincolor) in enumerate( + zip_longest( + connector.pins, connector.pinlabels, connector.pincolors + ) + ): + if ( + connector.hide_disconnected_pins + and not connector.visible_pins.get(pinname, False) + ): continue - pinhtml.append(' ') + + pinhtml.append(" ") if connector.ports_left: pinhtml.append(f' ') if pinlabel: - pinhtml.append(f' ') + pinhtml.append(f" ") if connector.pincolors: if pincolor in wv_colors._color_hex.keys(): + # fmt: off pinhtml.append(f' ') pinhtml.append( ' ') + # fmt: on else: - pinhtml.append( ' ') + pinhtml.append(' ') if connector.ports_right: pinhtml.append(f' ') - pinhtml.append(' ') + pinhtml.append(" ") - pinhtml.append('
{pinname}{pinlabel}{pinlabel}{translate_color(pincolor, self.options.color_mode)}') pinhtml.append( ' ') pinhtml.append(f' ') pinhtml.append( '
') pinhtml.append( ' 		{pinname}
') + pinhtml.append(" ") - html = [row.replace('', '\n'.join(pinhtml)) for row in html] + html = [ + row.replace("", "\n".join(pinhtml)) + for row in html + ] - html = '\n'.join(html) - dot.node(connector.name, label=f'<\n{html}\n>', shape='box', style='filled', - fillcolor=translate_color(self.options.bgcolor_connector, "HEX")) + html = "\n".join(html) + dot.node( + connector.name, + label=f"<\n{html}\n>", + shape="box", + style="filled", + fillcolor=translate_color(self.options.bgcolor_connector, "HEX"), + ) if len(connector.loops) > 0: - dot.attr('edge', color='#000000:#ffffff:#000000') + dot.attr("edge", color="#000000:#ffffff:#000000") if connector.ports_left: - loop_side = 'l' - loop_dir = 'w' + loop_side = "l" + loop_dir = "w" elif connector.ports_right: - loop_side = 'r' - loop_dir = 'e' + loop_side = "r" + loop_dir = "e" else: - raise Exception('No side for loops') + raise Exception("No side for loops") for loop in connector.loops: - dot.edge(f'{connector.name}:p{loop[0]}{loop_side}:{loop_dir}', - f'{connector.name}:p{loop[1]}{loop_side}:{loop_dir}') - + dot.edge( + f"{connector.name}:p{loop[0]}{loop_side}:{loop_dir}", + f"{connector.name}:p{loop[1]}{loop_side}:{loop_dir}", + ) # 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 - pad = any(len(colorstr) > 2 for cable in self.cables.values() for colorstr in cable.colors) + pad = any( + len(colorstr) > 2 + for cable in self.cables.values() + for colorstr in cable.colors + ) for cable in self.cables.values(): html = [] - awg_fmt = '' + awg_fmt = "" if cable.show_equiv: # Only convert units we actually know about, i.e. currently # mm2 and awg --- other units _are_ technically allowed, # and passed through as-is. - if cable.gauge_unit =='mm\u00B2': - awg_fmt = f' ({awg_equiv(cable.gauge)} AWG)' - elif cable.gauge_unit.upper() == 'AWG': - awg_fmt = f' ({mm2_equiv(cable.gauge)} mm\u00B2)' + if cable.gauge_unit == "mm\u00B2": + awg_fmt = f" ({awg_equiv(cable.gauge)} AWG)" + elif cable.gauge_unit.upper() == "AWG": + awg_fmt = f" ({mm2_equiv(cable.gauge)} mm\u00B2)" + # fmt: off rows = [[f'{html_bgcolor(cable.bgcolor_title)}{remove_links(cable.name)}' if cable.show_name else None], [pn_info_string(HEADER_PN, None, @@ -230,218 +313,387 @@ def create_graph(self) -> Graph: '', [html_image(cable.image)], [html_caption(cable.image)]] + # fmt: on rows.extend(get_additional_component_table(self, cable)) rows.append([html_line_breaks(cable.notes)]) html.extend(nested_html_table(rows, html_bgcolor_attr(cable.bgcolor))) wirehtml = [] - wirehtml.append('') # conductor table - wirehtml.append(' ') + # conductor table + wirehtml.append('
 
') + wirehtml.append(" ") - for i, (connection_color, wirelabel) in enumerate(zip_longest(cable.colors, cable.wirelabels), 1): - wirehtml.append(' ') - wirehtml.append(f' ') - wirehtml.append(f' ") + wirehtml.append(f" ") + wirehtml.append(f" ') - wirehtml.append(f' ') - wirehtml.append(' ') + wirehtml.append(f" ") + wirehtml.append(f" ") + wirehtml.append(" ") + # fmt: off bgcolors = ['#000000'] + get_color_hex(connection_color, pad=pad) + ['#000000'] - wirehtml.append(f' ') + wirehtml.append(f" ") wirehtml.append(f' ') - wirehtml.append(' ') - if cable.category == 'bundle': # for bundles individual wires can have part information + wirehtml.append("
 
') + for i, (connection_color, wirelabel) in enumerate( + zip_longest(cable.colors, cable.wirelabels), 1 + ): + wirehtml.append("
") wireinfo = [] if cable.show_wirenumbers: wireinfo.append(str(i)) - colorstr = wv_colors.translate_color(connection_color, self.options.color_mode) + colorstr = wv_colors.translate_color( + connection_color, self.options.color_mode + ) if colorstr: wireinfo.append(colorstr) if cable.wirelabels: - wireinfo.append(wirelabel if wirelabel is not None else '') + wireinfo.append(wirelabel if wirelabel is not None else "") wirehtml.append(f' {":".join(wireinfo)}') - wirehtml.append(f'
') wirehtml.append(' ') for j, bgcolor in enumerate(bgcolors[::-1]): # Reverse to match the curved wires when more than 2 colors wirehtml.append(f' ') - wirehtml.append('
') - wirehtml.append('
") + wirehtml.append(" ") + wirehtml.append(" ") + # fmt: on + + # for bundles, individual wires can have part information + if cable.category == "bundle": # create a list of wire parameters wireidentification = [] if isinstance(cable.pn, list): - wireidentification.append(pn_info_string(HEADER_PN, None, remove_links(cable.pn[i - 1]))) - manufacturer_info = pn_info_string(HEADER_MPN, - cable.manufacturer[i - 1] if isinstance(cable.manufacturer, list) else None, - cable.mpn[i - 1] if isinstance(cable.mpn, list) else None) - supplier_info = pn_info_string(HEADER_SPN, - cable.supplier[i - 1] if isinstance(cable.supplier, list) else None, - cable.spn[i - 1] if isinstance(cable.spn, list) else None) + wireidentification.append( + pn_info_string( + HEADER_PN, None, remove_links(cable.pn[i - 1]) + ) + ) + manufacturer_info = pn_info_string( + HEADER_MPN, + cable.manufacturer[i - 1] + if isinstance(cable.manufacturer, list) + else None, + cable.mpn[i - 1] if isinstance(cable.mpn, list) else None, + ) + supplier_info = pn_info_string( + HEADER_SPN, + cable.supplier[i - 1] + if isinstance(cable.supplier, list) + else None, + cable.spn[i - 1] if isinstance(cable.spn, list) else None, + ) if manufacturer_info: wireidentification.append(html_line_breaks(manufacturer_info)) if supplier_info: wireidentification.append(html_line_breaks(supplier_info)) # print parameters into a table row under the wire - if len(wireidentification) > 0 : + if len(wireidentification) > 0: + # fmt: off wirehtml.append(' ') wirehtml.append(' ') for attrib in wireidentification: - wirehtml.append(f' ') - wirehtml.append('
{attrib}
') - wirehtml.append(' ') + wirehtml.append(f" {attrib}") + wirehtml.append(" ") + wirehtml.append(" ") + # fmt: on if cable.shield: - wirehtml.append('  ') # spacer - wirehtml.append(' ') - wirehtml.append(' ') - wirehtml.append(' Shield') - wirehtml.append(' ') - wirehtml.append(' ') + wirehtml.append("  ") # spacer + wirehtml.append(" ") + wirehtml.append(" ") + wirehtml.append(" Shield") + wirehtml.append(" ") + wirehtml.append(" ") if isinstance(cable.shield, str): # shield is shown with specified color and black borders shield_color_hex = wv_colors.get_color_hex(cable.shield)[0] - attributes = f'height="6" bgcolor="{shield_color_hex}" border="2" sides="tb"' + attributes = ( + f'height="6" bgcolor="{shield_color_hex}" border="2" sides="tb"' + ) else: # shield is shown as a thin black wire attributes = f'height="2" bgcolor="#000000" border="0"' + # fmt: off wirehtml.append(f' ') + # fmt: on - wirehtml.append('  ') - wirehtml.append(' ') + wirehtml.append("  ") + wirehtml.append(" ") - html = [row.replace('', '\n'.join(wirehtml)) for row in html] + html = [ + row.replace("", "\n".join(wirehtml)) for row in html + ] # connections for connection in cable.connections: - if isinstance(connection.via_port, int): # check if it's an actual wire and not a shield - dot.attr('edge', color=':'.join(['#000000'] + wv_colors.get_color_hex(cable.colors[connection.via_port - 1], pad=pad) + ['#000000'])) + if isinstance(connection.via_port, int): + # check if it's an actual wire and not a shield + dot.attr( + "edge", + color=":".join( + ["#000000"] + + wv_colors.get_color_hex( + cable.colors[connection.via_port - 1], pad=pad + ) + + ["#000000"] + ), + ) else: # it's a shield connection # shield is shown with specified color and black borders, or as a thin black wire otherwise - dot.attr('edge', color=':'.join(['#000000', shield_color_hex, '#000000']) if isinstance(cable.shield, str) else '#000000') - if connection.from_port is not None: # connect to left + dot.attr( + "edge", + color=":".join(["#000000", shield_color_hex, "#000000"]) + if isinstance(cable.shield, str) + else "#000000", + ) + if connection.from_pin is not None: # connect to left from_connector = self.connectors[connection.from_name] - from_port = f':p{connection.from_port+1}r' if from_connector.style != 'simple' else '' - code_left_1 = f'{connection.from_name}{from_port}:e' - code_left_2 = f'{cable.name}:w{connection.via_port}:w' + from_pin_index = from_connector.pins.index(connection.from_pin) + from_port_str = ( + f":p{from_pin_index+1}r" + if from_connector.style != "simple" + else "" + ) + code_left_1 = f"{connection.from_name}{from_port_str}:e" + code_left_2 = f"{cable.name}:w{connection.via_port}:w" dot.edge(code_left_1, code_left_2) if from_connector.show_name: - from_info = [str(connection.from_name), str(self.connectors[connection.from_name].pins[connection.from_port])] + from_info = [ + str(connection.from_name), + str(connection.from_pin), + ] if from_connector.pinlabels: - pinlabel = from_connector.pinlabels[connection.from_port] - if pinlabel != '': + pinlabel = from_connector.pinlabels[from_pin_index] + if pinlabel != "": from_info.append(pinlabel) - from_string = ':'.join(from_info) + from_string = ":".join(from_info) else: - from_string = '' - html = [row.replace(f'', from_string) for row in html] - if connection.to_port is not None: # connect to right + from_string = "" + html = [ + row.replace(f"", from_string) + for row in html + ] + if connection.to_pin is not None: # connect to right to_connector = self.connectors[connection.to_name] - code_right_1 = f'{cable.name}:w{connection.via_port}:e' - to_port = f':p{connection.to_port+1}l' if self.connectors[connection.to_name].style != 'simple' else '' - code_right_2 = f'{connection.to_name}{to_port}:w' + to_pin_index = to_connector.pins.index(connection.to_pin) + to_port_str = ( + f":p{to_pin_index+1}l" if to_connector.style != "simple" else "" + ) + code_right_1 = f"{cable.name}:w{connection.via_port}:e" + code_right_2 = f"{connection.to_name}{to_port_str}:w" dot.edge(code_right_1, code_right_2) if to_connector.show_name: - to_info = [str(connection.to_name), str(self.connectors[connection.to_name].pins[connection.to_port])] + to_info = [str(connection.to_name), str(connection.to_pin)] if to_connector.pinlabels: - pinlabel = to_connector.pinlabels[connection.to_port] - if pinlabel != '': + pinlabel = to_connector.pinlabels[to_pin_index] + if pinlabel != "": to_info.append(pinlabel) - to_string = ':'.join(to_info) + to_string = ":".join(to_info) else: - to_string = '' - html = [row.replace(f'', to_string) for row in html] - - style, bgcolor = ('filled,dashed', self.options.bgcolor_bundle) if cable.category == 'bundle' else \ - ('filled', self.options.bgcolor_cable) - html = '\n'.join(html) - dot.node(cable.name, label=f'<\n{html}\n>', shape='box', - style=style, fillcolor=translate_color(bgcolor, "HEX")) + to_string = "" + html = [ + row.replace(f"", to_string) + for row in html + ] + + style, bgcolor = ( + ("filled,dashed", self.options.bgcolor_bundle) + if cable.category == "bundle" + else ("filled", self.options.bgcolor_cable) + ) + html = "\n".join(html) + dot.node( + cable.name, + label=f"<\n{html}\n>", + shape="box", + style=style, + fillcolor=translate_color(bgcolor, "HEX"), + ) def typecheck(name: str, value: Any, expect: type) -> None: if not isinstance(value, expect): - raise Exception(f'Unexpected value type of {name}: Expected {expect}, got {type(value)}\n{value}') + raise Exception( + f"Unexpected value type of {name}: Expected {expect}, got {type(value)}\n{value}" + ) # TODO?: Differ between override attributes and HTML? if self.tweak.override is not None: - typecheck('tweak.override', self.tweak.override, dict) + typecheck("tweak.override", self.tweak.override, dict) for k, d in self.tweak.override.items(): - typecheck(f'tweak.override.{k} key', k, str) - typecheck(f'tweak.override.{k} value', d, dict) + typecheck(f"tweak.override.{k} key", k, str) + typecheck(f"tweak.override.{k} value", d, dict) for a, v in d.items(): - typecheck(f'tweak.override.{k}.{a} key', a, str) - typecheck(f'tweak.override.{k}.{a} value', v, (str, type(None))) + typecheck(f"tweak.override.{k}.{a} key", a, str) + typecheck(f"tweak.override.{k}.{a} value", v, (str, type(None))) # Override generated attributes of selected entries matching tweak.override. for i, entry in enumerate(dot.body): if isinstance(entry, str): # Find a possibly quoted keyword after leading TAB(s) and followed by [ ]. - match = re.match(r'^\t*(")?((?(1)[^"]|[^ "])+)(?(1)") \[.*\]$', entry, re.S) + match = re.match( + r'^\t*(")?((?(1)[^"]|[^ "])+)(?(1)") \[.*\]$', entry, re.S + ) keyword = match and match[2] if keyword in self.tweak.override.keys(): for attr, value in self.tweak.override[keyword].items(): if value is None: - entry, n_subs = re.subn(f'( +)?{attr}=("[^"]*"|[^] ]*)(?(1)| *)', '', entry) + entry, n_subs = re.subn( + f'( +)?{attr}=("[^"]*"|[^] ]*)(?(1)| *)', "", entry + ) if n_subs < 1: - print(f'Harness.create_graph() warning: {attr} not found in {keyword}!') + print( + f"Harness.create_graph() warning: {attr} not found in {keyword}!" + ) elif n_subs > 1: - print(f'Harness.create_graph() warning: {attr} removed {n_subs} times in {keyword}!') + print( + f"Harness.create_graph() warning: {attr} removed {n_subs} times in {keyword}!" + ) continue - if len(value) == 0 or ' ' in value: - value = value.replace('"', r'\"') + if len(value) == 0 or " " in value: + value = value.replace('"', r"\"") value = f'"{value}"' - entry, n_subs = re.subn(f'{attr}=("[^"]*"|[^] ]*)', f'{attr}={value}', entry) + entry, n_subs = re.subn( + f'{attr}=("[^"]*"|[^] ]*)', f"{attr}={value}", entry + ) if n_subs < 1: # If attr not found, then append it - entry = re.sub(r'\]$', f' {attr}={value}]', entry) + entry = re.sub(r"\]$", f" {attr}={value}]", entry) elif n_subs > 1: - print(f'Harness.create_graph() warning: {attr} overridden {n_subs} times in {keyword}!') + print( + f"Harness.create_graph() warning: {attr} overridden {n_subs} times in {keyword}!" + ) dot.body[i] = entry if self.tweak.append is not None: if isinstance(self.tweak.append, list): for i, element in enumerate(self.tweak.append, 1): - typecheck(f'tweak.append[{i}]', element, str) + typecheck(f"tweak.append[{i}]", element, str) dot.body.extend(self.tweak.append) else: - typecheck('tweak.append', self.tweak.append, str) + typecheck("tweak.append", self.tweak.append, str) dot.body.append(self.tweak.append) + for mate in self.mates: + if mate.shape[0] == "<" and mate.shape[-1] == ">": + dir = "both" + elif mate.shape[0] == "<": + dir = "back" + elif mate.shape[-1] == ">": + dir = "forward" + else: + dir = "none" + + if isinstance(mate, MatePin): + color = "#000000" + elif isinstance(mate, MateComponent): + color = "#000000:#000000" + else: + raise Exception(f"{mate} is an unknown mate") + + from_connector = self.connectors[mate.from_name] + if ( + isinstance(mate, MatePin) + and self.connectors[mate.from_name].style != "simple" + ): + from_pin_index = from_connector.pins.index(mate.from_pin) + from_port_str = f":p{from_pin_index+1}r" + else: # MateComponent or style == 'simple' + from_port_str = "" + if ( + isinstance(mate, MatePin) + and self.connectors[mate.to_name].style != "simple" + ): + to_pin_index = to_connector.pins.index(mate.to_pin) + to_port_str = ( + f":p{to_pin_index+1}l" + if isinstance(mate, MatePin) + and self.connectors[mate.to_name].style != "simple" + else "" + ) + else: # MateComponent or style == 'simple' + to_port_str = "" + code_from = f"{mate.from_name}{from_port_str}:e" + to_connector = self.connectors[mate.to_name] + code_to = f"{mate.to_name}{to_port_str}:w" + + dot.attr("edge", color=color, style="dashed", dir=dir) + dot.edge(code_from, code_to) + return dot + # cache for the GraphViz Graph object + # do not access directly, use self.graph instead + _graph = None + + @property + def graph(self): + if not self._graph: # no cached graph exists, generate one + self._graph = self.create_graph() + return self._graph # return cached graph + @property def png(self): from io import BytesIO - graph = self.create_graph() + + graph = self.graph data = BytesIO() - data.write(graph.pipe(format='png')) + data.write(graph.pipe(format="png")) data.seek(0) return data.read() @property def svg(self): from io import BytesIO - graph = self.create_graph() + + graph = self.graph data = BytesIO() - data.write(graph.pipe(format='svg')) + data.write(graph.pipe(format="svg")) data.seek(0) return data.read() - def output(self, filename: (str, Path), view: bool = False, cleanup: bool = True, fmt: tuple = ('pdf', )) -> None: + def output( + self, + filename: (str, Path), + view: bool = False, + cleanup: bool = True, + fmt: tuple = ("html", "png", "svg", "tsv"), + ) -> None: + # graphical output + graph = self.graph + svg_already_exists = Path( + f"{filename}.svg" + ).exists() # if SVG already exists, do not delete later # graphical output - graph = self.create_graph() for f in fmt: - graph.format = f - graph.render(filename=filename, view=view, cleanup=cleanup) - graph.save(filename=f'{filename}.gv') - # bom output + if f in ("png", "svg", "html"): + if f == "html": # if HTML format is specified, + f = "svg" # generate SVG for embedding into HTML + # TODO: prevent rendering SVG twice when both SVG and HTML are specified + graph.format = f + graph.render(filename=filename, view=view, cleanup=cleanup) + # GraphViz output + if "gv" in fmt: + graph.save(filename=f"{filename}.gv") + # BOM output bomlist = bom_list(self.bom()) - with open_file_write(f'{filename}.bom.tsv') as file: - file.write(tuplelist2tsv(bomlist)) + if "tsv" in fmt: + open_file_write(f"{filename}.bom.tsv").write(tuplelist2tsv(bomlist)) + if "csv" in fmt: + # TODO: implement CSV output (preferrably using CSV library) + print("CSV output is not yet supported") # HTML output - generate_html_output(filename, bomlist, self.metadata, self.options) + if "html" in fmt: + generate_html_output(filename, bomlist, self.metadata, self.options) + # PDF output + if "pdf" in fmt: + # TODO: implement PDF output + print("PDF output is not yet supported") + # delete SVG if not needed + if "html" in fmt and not "svg" in fmt and not svg_already_exists: + Path(f"{filename}.svg").unlink() def bom(self): if not self._bom: diff --git a/src/wireviz/__init__.py b/src/wireviz/__init__.py index 178fbf18..08f7167a 100644 --- a/src/wireviz/__init__.py +++ b/src/wireviz/__init__.py @@ -1,8 +1,8 @@ # -*- coding: utf-8 -*- # Please don't import anything in this file to avoid issues when it is imported in setup.py -__version__ = '0.4-dev' +__version__ = "0.4-dev" -CMD_NAME = 'wireviz' # Lower case command and module name -APP_NAME = 'WireViz' # Application name in texts meant to be human readable -APP_URL = 'https://github.com/formatc1702/WireViz' +CMD_NAME = "wireviz" # Lower case command and module name +APP_NAME = "WireViz" # Application name in texts meant to be human readable +APP_URL = "https://github.com/formatc1702/WireViz" diff --git a/src/wireviz/build_examples.py b/src/wireviz/build_examples.py index 65a10f6b..e54d0f5c 100755 --- a/src/wireviz/build_examples.py +++ b/src/wireviz/build_examples.py @@ -2,46 +2,48 @@ # -*- coding: utf-8 -*- import argparse -import sys import os +import sys from pathlib import Path script_path = Path(__file__).absolute() sys.path.insert(0, str(script_path.parent.parent)) # to find wireviz module -from wireviz import wireviz, __version__, APP_NAME -from wv_helper import open_file_write, open_file_read, open_file_append +from wv_helper import open_file_append, open_file_read, open_file_write +from wireviz import APP_NAME, __version__, wireviz dir = script_path.parent.parent.parent -readme = 'readme.md' +readme = "readme.md" groups = { - 'examples': { - 'path': dir / 'examples', - 'prefix': 'ex', - readme: [], # Include no files - 'title': 'Example Gallery', + "examples": { + "path": dir / "examples", + "prefix": "ex", + readme: [], # Include no files + "title": "Example Gallery", }, - 'tutorial' : { - 'path': dir / 'tutorial', - 'prefix': 'tutorial', - readme: ['md', 'yml'], # Include .md and .yml files - 'title': f'{APP_NAME} Tutorial', + "tutorial": { + "path": dir / "tutorial", + "prefix": "tutorial", + readme: ["md", "yml"], # Include .md and .yml files + "title": f"{APP_NAME} Tutorial", }, - 'demos' : { - 'path': dir / 'examples', - 'prefix': 'demo', + "demos": { + "path": dir / "examples", + "prefix": "demo", }, } -input_extensions = ['.yml'] -extensions_not_containing_graphviz_output = ['.gv', '.bom.tsv'] -extensions_containing_graphviz_output = ['.png', '.svg', '.html'] -generated_extensions = extensions_not_containing_graphviz_output + extensions_containing_graphviz_output +input_extensions = [".yml"] +extensions_not_containing_graphviz_output = [".gv", ".bom.tsv"] +extensions_containing_graphviz_output = [".png", ".svg", ".html"] +generated_extensions = ( + extensions_not_containing_graphviz_output + extensions_containing_graphviz_output +) def collect_filenames(description, groupkey, ext_list): - path = groups[groupkey]['path'] + path = groups[groupkey]["path"] patterns = [f"{groups[groupkey]['prefix']}*{ext}" for ext in ext_list] if ext_list != input_extensions and readme in groups[groupkey]: patterns.append(readme) @@ -52,107 +54,141 @@ def collect_filenames(description, groupkey, ext_list): def build_generated(groupkeys): for key in groupkeys: # preparation - path = groups[key]['path'] + path = groups[key]["path"] build_readme = readme in groups[key] if build_readme: - include_readme = 'md' in groups[key][readme] - include_source = 'yml' in groups[key][readme] + include_readme = "md" in groups[key][readme] + include_source = "yml" in groups[key][readme] with open_file_write(path / readme) as out: out.write(f'# {groups[key]["title"]}\n\n') # collect and iterate input YAML files - for yaml_file in collect_filenames('Building', key, input_extensions): + for yaml_file in collect_filenames("Building", key, input_extensions): print(f' "{yaml_file}"') - wireviz.parse_file(yaml_file) + wireviz.parse(yaml_file, output_formats=("gv", "html", "png", "svg", "tsv")) if build_readme: - i = ''.join(filter(str.isdigit, yaml_file.stem)) + i = "".join(filter(str.isdigit, yaml_file.stem)) with open_file_append(path / readme) as out: if include_readme: - with open_file_read(yaml_file.with_suffix('.md')) as info: + with open_file_read(yaml_file.with_suffix(".md")) as info: for line in info: - out.write(line.replace('## ', f'## {i} - ')) - out.write('\n\n') + out.write(line.replace("## ", f"## {i} - ")) + out.write("\n\n") else: - out.write(f'## Example {i}\n') + out.write(f"## Example {i}\n") if include_source: with open_file_read(yaml_file) as src: - out.write('```yaml\n') + out.write("```yaml\n") for line in src: out.write(line) - out.write('```\n') - out.write('\n') + out.write("```\n") + out.write("\n") - out.write(f'![]({yaml_file.stem}.png)\n\n') - out.write(f'[Source]({yaml_file.name}) - [Bill of Materials]({yaml_file.stem}.bom.tsv)\n\n\n') + out.write(f"![]({yaml_file.stem}.png)\n\n") + out.write( + f"[Source]({yaml_file.name}) - [Bill of Materials]({yaml_file.stem}.bom.tsv)\n\n\n" + ) def clean_generated(groupkeys): for key in groupkeys: # collect and remove files - for filename in collect_filenames('Cleaning', key, generated_extensions): + for filename in collect_filenames("Cleaning", key, generated_extensions): if filename.is_file(): print(f' rm "{filename}"') - os.remove(filename) + Path(filename).unlink() -def compare_generated(groupkeys, branch = '', include_graphviz_output = False): +def compare_generated(groupkeys, branch="", include_graphviz_output=False): if branch: - branch = f' {branch.strip()}' - compare_extensions = generated_extensions if include_graphviz_output else extensions_not_containing_graphviz_output + branch = f" {branch.strip()}" + compare_extensions = ( + generated_extensions + if include_graphviz_output + else extensions_not_containing_graphviz_output + ) for key in groupkeys: # collect and compare files - for filename in collect_filenames('Comparing', key, compare_extensions): + for filename in collect_filenames("Comparing", key, compare_extensions): cmd = f'git --no-pager diff{branch} -- "{filename}"' - print(f' {cmd}') + print(f" {cmd}") os.system(cmd) -def restore_generated(groupkeys, branch = ''): +def restore_generated(groupkeys, branch=""): if branch: - branch = f' {branch.strip()}' + branch = f" {branch.strip()}" for key in groupkeys: # collect input YAML files - filename_list = collect_filenames('Restoring', key, input_extensions) + filename_list = collect_filenames("Restoring", key, input_extensions) # collect files to restore - filename_list = [fn.with_suffix(ext) for fn in filename_list for ext in generated_extensions] + filename_list = [ + fn.with_suffix(ext) for fn in filename_list for ext in generated_extensions + ] if readme in groups[key]: - filename_list.append(groups[key]['path'] / readme) + filename_list.append(groups[key]["path"] / readme) # restore files for filename in filename_list: cmd = f'git checkout{branch} -- "{filename}"' - print(f' {cmd}') + print(f" {cmd}") os.system(cmd) def parse_args(): - parser = argparse.ArgumentParser(description=f'{APP_NAME} Example Manager',) - parser.add_argument('-V', '--version', action='version', version=f'%(prog)s - {APP_NAME} {__version__}') - parser.add_argument('action', nargs='?', action='store', - choices=['build','clean','compare','diff','restore'], default='build', - help='what to do with the generated files (default: build)') - parser.add_argument('-c', '--compare-graphviz-output', action='store_true', - help='the Graphviz output is also compared (default: False)') - parser.add_argument('-b', '--branch', action='store', default='', - help='branch or commit to compare with or restore from') - parser.add_argument('-g', '--groups', nargs='+', - choices=groups.keys(), default=groups.keys(), - help='the groups of generated files (default: all)') + parser = argparse.ArgumentParser( + description=f"{APP_NAME} Example Manager", + ) + parser.add_argument( + "-V", + "--version", + action="version", + version=f"%(prog)s - {APP_NAME} {__version__}", + ) + parser.add_argument( + "action", + nargs="?", + action="store", + choices=["build", "clean", "compare", "diff", "restore"], + default="build", + help="what to do with the generated files (default: build)", + ) + parser.add_argument( + "-c", + "--compare-graphviz-output", + action="store_true", + help="the Graphviz output is also compared (default: False)", + ) + parser.add_argument( + "-b", + "--branch", + action="store", + default="", + help="branch or commit to compare with or restore from", + ) + parser.add_argument( + "-g", + "--groups", + nargs="+", + choices=groups.keys(), + default=groups.keys(), + help="the groups of generated files (default: all)", + ) return parser.parse_args() def main(): args = parse_args() - if args.action == 'build': + if args.action == "build": build_generated(args.groups) - elif args.action == 'clean': + elif args.action == "clean": clean_generated(args.groups) - elif args.action == 'compare' or args.action == 'diff': + elif args.action == "compare" or args.action == "diff": compare_generated(args.groups, args.branch, args.compare_graphviz_output) - elif args.action == 'restore': + elif args.action == "restore": restore_generated(args.groups, args.branch) -if __name__ == '__main__': +if __name__ == "__main__": main() diff --git a/src/wireviz/templates/din-6771.html b/src/wireviz/templates/din-6771.html new file mode 100644 index 00000000..547a340c --- /dev/null +++ b/src/wireviz/templates/din-6771.html @@ -0,0 +1,286 @@ + + + + + + + <!-- %title% --> + + + + +
+
+ +
+ +
+ +
+ + + +
+ +
+ +
+ +
+ +
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
DateName
Sheet
of
RevChangelogDateName
+
+ +
+
+ + diff --git a/src/wireviz/templates/simple.html b/src/wireviz/templates/simple.html new file mode 100644 index 00000000..cbb44659 --- /dev/null +++ b/src/wireviz/templates/simple.html @@ -0,0 +1,45 @@ + + + + + <!-- %title% --> + + +

+

Diagram

+ +
+ +
+ +
+ +
+ +
+ +
+ +

Bill of Materials

+ +
+ +
+ + diff --git a/src/wireviz/wireviz.py b/src/wireviz/wireviz.py index 95674945..11016192 100755 --- a/src/wireviz/wireviz.py +++ b/src/wireviz/wireviz.py @@ -1,265 +1,436 @@ #!/usr/bin/env python3 # -*- coding: utf-8 -*- -import argparse -import os -from pathlib import Path import sys -from typing import Any, Tuple +from pathlib import Path +from typing import Any, Dict, List, Tuple, Union import yaml -if __name__ == '__main__': - sys.path.insert(0, os.path.join(os.path.dirname(__file__), '..')) +if __name__ == "__main__": + sys.path.insert(0, str(Path(__file__).parent.parent)) # add src/wireviz to PATH -from wireviz import __version__ from wireviz.DataClasses import Metadata, Options, Tweak from wireviz.Harness import Harness -from wireviz.wv_helper import expand, open_file_read - - -def parse(yaml_input: str, file_out: (str, Path) = None, return_types: (None, str, Tuple[str]) = None) -> Any: +from wireviz.wv_helper import ( + expand, + get_single_key_and_value, + is_arrow, + open_file_read, + smart_file_resolve, +) + + +def parse( + inp: Union[Path, str, Dict], + return_types: Union[None, str, Tuple[str]] = None, + output_formats: Union[None, str, Tuple[str]] = None, + output_dir: Union[str, Path] = None, + output_name: Union[None, str] = None, + image_paths: Union[Path, str, List] = [], +) -> Any: """ - Parses yaml input string and does the high-level harness conversion - - :param yaml_input: a string containing the yaml input data - :param file_out: - :param return_types: if None, then returns None; if the value is a string, then a - corresponding data format will be returned; if the value is a tuple of strings, - then for every valid format in the `return_types` tuple, another return type - will be generated and returned in the same order; currently supports: - - "png" - will return the PNG data - - "svg" - will return the SVG data - - "harness" - will return the `Harness` instance + This function takes an input, parses it as a WireViz Harness file, + and outputs the result as one or more files and/or as a function return value + + Accepted inputs: + * A path to a YAML source file to parse + * A string containing the YAML data to parse + * A Python Dict containing the pre-parsed YAML data + + Supported return types: + * "png": the diagram as raw PNG data + * "svg": the diagram as raw SVG data + * "harness": the diagram as a Harness Python object + + Supported output formats: + * "csv": the BOM, as a comma-separated text file + * "gv": the diagram, as a GraphViz source file + * "html": the diagram and (depending on the template) the BOM, as a HTML file + * "png": the diagram, as a PNG raster image + * "pdf": the diagram and (depending on the template) the BOM, as a PDF file + * "svg": the diagram, as a SVG vector image + * "tsv": the BOM, as a tab-separated text file + + Args: + inp (Path | str | Dict): + The input to be parsed (see above for accepted inputs). + return_types (optional): + One of the supported return types (see above), or a tuple of multiple return types. + If set to None, no output is returned by the function. + output_formats (optional): + One of the supported output types (see above), or a tuple of multiple output formats. + If set to None, no files are generated. + output_dir (Path | str, optional): + The directory to place the generated output files. + Defaults to inp's parent directory, or cwd if inp is not a path. + output_name (str, optional): + The name to use for the generated output files (without extension). + Defaults to inp's file name (without extension). + Required parameter if inp is not a path. + image_paths (Path | str | List, optional): + Paths to use when resolving any image paths included in the data. + Note: If inp is a path to a YAML file, + its parent directory will automatically be included in the list. + + Returns: + Depending on the return_types parameter, may return: + * None + * one of the following, or a tuple containing two or more of the following: + * PNG data + * SVG data + * a Harness object """ - yaml_data = yaml.safe_load(yaml_input) - + if not output_formats and not return_types: + raise Exception("No output formats or return types specified") + + yaml_data, yaml_file = _get_yaml_data_and_path(inp) + if output_formats: + # need to write data to file, determine output directory and filename + output_dir = _get_output_dir(yaml_file, output_dir) + output_name = _get_output_name(yaml_file, output_name) + output_file = output_dir / output_name + + if yaml_file: + # if reading from file, ensure that input file's parent directory is included in image_paths + default_image_path = yaml_file.parent.resolve() + if not default_image_path in [Path(x).resolve() for x in image_paths]: + image_paths.append(default_image_path) + + # define variables ========================================================= + # containers for parsed component data and connection sets + template_connectors = {} + template_cables = {} + connection_sets = [] + # actual harness harness = Harness( - metadata = Metadata(**yaml_data.get('metadata', {})), - options = Options(**yaml_data.get('options', {})), - tweak = Tweak(**yaml_data.get('tweak', {})), + metadata=Metadata(**yaml_data.get("metadata", {})), + options=Options(**yaml_data.get("options", {})), + tweak=Tweak(**yaml_data.get("tweak", {})), ) - if 'title' not in harness.metadata: - harness.metadata['title'] = Path(file_out).stem + # others + # store mapping of components to their respective template + designators_and_templates = {} + # keep track of auto-generated designators to avoid duplicates + autogenerated_designators = {} + + if "title" not in harness.metadata: + harness.metadata["title"] = Path(yaml_file).stem if yaml_file else "" # add items - sections = ['connectors', 'cables', 'connections'] + # parse YAML input file ==================================================== + + sections = ["connectors", "cables", "connections"] types = [dict, dict, list] for sec, ty in zip(sections, types): - if sec in yaml_data and type(yaml_data[sec]) == ty: - if len(yaml_data[sec]) > 0: + if sec in yaml_data and type(yaml_data[sec]) == ty: # section exists + if len(yaml_data[sec]) > 0: # section has contents if ty == dict: for key, attribs in yaml_data[sec].items(): # The Image dataclass might need to open an image file with a relative path. - image = attribs.get('image') + image = attribs.get("image") if isinstance(image, dict): - image['gv_dir'] = Path(file_out if file_out else '').parent # Inject context - - if sec == 'connectors': - if not attribs.get('autogenerate', False): - harness.add_connector(name=key, **attribs) - elif sec == 'cables': - harness.add_cable(name=key, **attribs) - else: - pass # section exists but is empty + image_path = image["src"] + if image_path and not Path(image_path).is_absolute(): + # resolve relative image path + image["src"] = smart_file_resolve( + image_path, image_paths + ) + if sec == "connectors": + template_connectors[key] = attribs + elif sec == "cables": + template_cables[key] = attribs + else: # section exists but is empty + pass else: # section does not exist, create empty section if ty == dict: yaml_data[sec] = {} elif ty == list: yaml_data[sec] = [] - # add connections - - def check_designators(what, where): # helper function - for i, x in enumerate(what): - if x not in yaml_data[where[i]]: - return False - return True - - autogenerated_ids = {} - for connection in yaml_data['connections']: - # find first component (potentially nested inside list or dict) - first_item = connection[0] - if isinstance(first_item, list): - first_item = first_item[0] - elif isinstance(first_item, dict): - first_item = list(first_item.keys())[0] - elif isinstance(first_item, str): - pass - - # check which section the first item belongs to - alternating_sections = ['connectors','cables'] - for index, section in enumerate(alternating_sections): - if first_item in yaml_data[section]: - expected_index = index - break + connection_sets = yaml_data["connections"] + + # go through connection sets, generate and connect components ============== + + template_separator_char = harness.options.template_separator + + def resolve_designator(inp, separator): + if separator in inp: # generate a new instance of an item + if inp.count(separator) > 1: + raise Exception(f"{inp} - Found more than one separator ({separator})") + template, designator = inp.split(separator) + if designator == "": + autogenerated_designators[template] = ( + autogenerated_designators.get(template, 0) + 1 + ) + designator = f"__{template}_{autogenerated_designators[template]}" + # check if redefining existing component to different template + if designator in designators_and_templates: + if designators_and_templates[designator] != template: + raise Exception( + f"Trying to redefine {designator} from {designators_and_templates[designator]} to {template}" + ) + else: + designators_and_templates[designator] = template else: - raise Exception('First item not found anywhere.') - expected_index = 1 - expected_index # flip once since it is flipped back at the *beginning* of every loop - - # check that all iterable items (lists and dicts) are the same length - # and that they are alternating between connectors and cables/bundles, starting with either - itemcount = None - for item in connection: - expected_index = 1 - expected_index # make sure items alternate between connectors and cables - expected_section = alternating_sections[expected_index] - if isinstance(item, list): - itemcount_new = len(item) - for subitem in item: - if not subitem in yaml_data[expected_section]: - raise Exception(f'{subitem} is not in {expected_section}') - elif isinstance(item, dict): - if len(item.keys()) != 1: - raise Exception('Dicts may contain only one key here!') - itemcount_new = len(expand(list(item.values())[0])) - subitem = list(item.keys())[0] - if not subitem in yaml_data[expected_section]: - raise Exception(f'{subitem} is not in {expected_section}') - elif isinstance(item, str): - if not item in yaml_data[expected_section]: - raise Exception(f'{item} is not in {expected_section}') - continue - if itemcount is not None and itemcount_new != itemcount: - raise Exception('All lists and dict lists must be the same length!') - itemcount = itemcount_new - if itemcount is None: - raise Exception('No item revealed the number of connections to make!') - - # populate connection list - connection_list = [] - for i, item in enumerate(connection): - if isinstance(item, str): # one single-pin component was specified - sublist = [] - for i in range(1, itemcount + 1): - if yaml_data['connectors'][item].get('autogenerate'): - autogenerated_ids[item] = autogenerated_ids.get(item, 0) + 1 - new_id = f'_{item}_{autogenerated_ids[item]}' - harness.add_connector(new_id, **yaml_data['connectors'][item]) - sublist.append([new_id, 1]) - else: - sublist.append([item, 1]) - connection_list.append(sublist) - elif isinstance(item, list): # a list of single-pin components were specified - sublist = [] - for subitem in item: - if yaml_data['connectors'][subitem].get('autogenerate'): - autogenerated_ids[subitem] = autogenerated_ids.get(subitem, 0) + 1 - new_id = f'_{subitem}_{autogenerated_ids[subitem]}' - harness.add_connector(new_id, **yaml_data['connectors'][subitem]) - sublist.append([new_id, 1]) - else: - sublist.append([subitem, 1]) - connection_list.append(sublist) - elif isinstance(item, dict): # a component with multiple pins was specified - sublist = [] - id = list(item.keys())[0] - pins = expand(list(item.values())[0]) - for pin in pins: - sublist.append([id, pin]) - connection_list.append(sublist) + template, designator = (inp, inp) + if designator in designators_and_templates: + pass # referencing an exiting connector, no need to add again + else: + designators_and_templates[designator] = template + return (template, designator) + + # utilities to check for alternating connectors and cables/arrows ========== + + alternating_types = ["connector", "cable/arrow"] + expected_type = None + + def check_type(designator, template, actual_type): + nonlocal expected_type + if not expected_type: # each connection set may start with either section + expected_type = actual_type + + if actual_type != expected_type: # did not alternate + raise Exception( + f'Expected {expected_type}, but "{designator}" ("{template}") is {actual_type}' + ) + + def alternate_type(): # flip between connector and cable/arrow + nonlocal expected_type + expected_type = alternating_types[1 - alternating_types.index(expected_type)] + + for connection_set in connection_sets: + + # figure out number of parallel connections within this set + connectioncount = [] + for entry in connection_set: + if isinstance(entry, list): + connectioncount.append(len(entry)) + elif isinstance(entry, dict): + connectioncount.append(len(expand(list(entry.values())[0]))) + # e.g.: - X1: [1-4,6] yields 5 + else: + pass # strings do not reveal connectioncount + if not any(connectioncount): + # no item in the list revealed connection count; + # assume connection count is 1 + connectioncount = [1] + # Example: The following is a valid connection set, + # even though no item reveals the connection count; + # the count is not needed because only a component-level mate happens. + # - + # - CONNECTOR + # - ==> + # - CONNECTOR + + # check that all entries are the same length + if len(set(connectioncount)) > 1: + raise Exception( + "All items in connection set must reference the same number of connections" + ) + # all entries are the same length, connection count is set + connectioncount = connectioncount[0] + + # expand string entries to list entries of correct length + for index, entry in enumerate(connection_set): + if isinstance(entry, str): + connection_set[index] = [entry] * connectioncount + + # resolve all designators + for index, entry in enumerate(connection_set): + if isinstance(entry, list): + for subindex, item in enumerate(entry): + template, designator = resolve_designator( + item, template_separator_char + ) + connection_set[index][subindex] = designator + elif isinstance(entry, dict): + key = list(entry.keys())[0] + template, designator = resolve_designator(key, template_separator_char) + value = entry[key] + connection_set[index] = {designator: value} else: - raise Exception('Unexpected item in connection list') - - # actually connect components using connection list - for i, item in enumerate(connection_list): - id = item[0][0] # TODO: make more elegant/robust/pythonic - if id in harness.cables: - for j, con in enumerate(item): - if i == 0: # list started with a cable, no connector to join on left side - from_name = None - from_pin = None + pass # string entries have been expanded in previous step + + # expand all pin lists + for index, entry in enumerate(connection_set): + if isinstance(entry, list): + connection_set[index] = [{designator: 1} for designator in entry] + elif isinstance(entry, dict): + designator = list(entry.keys())[0] + pinlist = expand(entry[designator]) + connection_set[index] = [{designator: pin} for pin in pinlist] + else: + pass # string entries have been expanded in previous step + + # Populate wiring harness ============================================== + + expected_type = None # reset check for alternating types + # at the beginning of every connection set + # since each set may begin with either type + + # generate components + for entry in connection_set: + for item in entry: + designator = list(item.keys())[0] + template = designators_and_templates[designator] + + if designator in harness.connectors: # existing connector instance + check_type(designator, template, "connector") + elif template in template_connectors.keys(): + # generate new connector instance from template + check_type(designator, template, "connector") + harness.add_connector( + name=designator, **template_connectors[template] + ) + + elif designator in harness.cables: # existing cable instance + check_type(designator, template, "cable/arrow") + elif template in template_cables.keys(): + # generate new cable instance from template + check_type(designator, template, "cable/arrow") + harness.add_cable(name=designator, **template_cables[template]) + + elif is_arrow(designator): + check_type(designator, template, "cable/arrow") + # arrows do not need to be generated here + else: + raise Exception( + f"{template} is an unknown template/designator/arrow." + ) + + alternate_type() # entries in connection set must alternate between connectors and cables/arrows + + # transpose connection set list + # before: one item per component, one subitem per connection in set + # after: one item per connection in set, one subitem per component + connection_set = list(map(list, zip(*connection_set))) + + # connect components + for index_entry, entry in enumerate(connection_set): + for index_item, item in enumerate(entry): + designator = list(item.keys())[0] + + if designator in harness.cables: + if index_item == 0: + # list started with a cable, no connector to join on left side + from_name, from_pin = (None, None) else: - from_name = connection_list[i-1][j][0] - from_pin = connection_list[i-1][j][1] - via_name = item[j][0] - via_pin = item[j][1] - if i == len(connection_list) - 1: # list ends with a cable, no connector to join on right side - to_name = None - to_pin = None + from_name, from_pin = get_single_key_and_value( + entry[index_item - 1] + ) + via_name, via_pin = (designator, item[designator]) + if index_item == len(entry) - 1: + # list ends with a cable, no connector to join on right side + to_name, to_pin = (None, None) else: - to_name = connection_list[i+1][j][0] - to_pin = connection_list[i+1][j][1] - harness.connect(from_name, from_pin, via_name, via_pin, to_name, to_pin) + to_name, to_pin = get_single_key_and_value( + entry[index_item + 1] + ) + harness.connect( + from_name, from_pin, via_name, via_pin, to_name, to_pin + ) + + elif is_arrow(designator): + if index_item == 0: # list starts with an arrow + raise Exception( + "An arrow cannot be at the start of a connection set" + ) + elif index_item == len(entry) - 1: # list ends with an arrow + raise Exception( + "An arrow cannot be at the end of a connection set" + ) + + from_name, from_pin = get_single_key_and_value( + entry[index_item - 1] + ) + via_name, via_pin = (designator, None) + to_name, to_pin = get_single_key_and_value(entry[index_item + 1]) + if "-" in designator: # mate pin by pin + harness.add_mate_pin( + from_name, from_pin, to_name, to_pin, designator + ) + elif "=" in designator and index_entry == 0: + # mate two connectors as a whole + harness.add_mate_component(from_name, to_name, designator) + + # harness population completed ============================================= if "additional_bom_items" in yaml_data: for line in yaml_data["additional_bom_items"]: harness.add_bom_item(line) - if file_out is not None: - harness.output(filename=file_out, fmt=('png', 'svg'), view=False) + if output_formats: + harness.output(filename=output_file, fmt=output_formats, view=False) - if return_types is not None: + if return_types: returns = [] - if isinstance(return_types, str): # only one return type speficied + if isinstance(return_types, str): # only one return type speficied return_types = [return_types] return_types = [t.lower() for t in return_types] for rt in return_types: - if rt == 'png': + if rt == "png": returns.append(harness.png) - if rt == 'svg': + if rt == "svg": returns.append(harness.svg) - if rt == 'harness': + if rt == "harness": returns.append(harness) return tuple(returns) if len(returns) != 1 else returns[0] -def parse_file(yaml_file: str, file_out: (str, Path) = None) -> None: - with open_file_read(yaml_file) as file: - yaml_input = file.read() - - if not file_out: - fn, fext = os.path.splitext(yaml_file) - file_out = fn - file_out = os.path.abspath(file_out) - - parse(yaml_input, file_out=file_out) - - -def parse_cmdline(): - parser = argparse.ArgumentParser( - description='Generate cable and wiring harness documentation from YAML descriptions', - ) - parser.add_argument('-V', '--version', action='version', version='%(prog)s ' + __version__) - parser.add_argument('input_file', action='store', type=str, metavar='YAML_FILE') - parser.add_argument('-o', '--output_file', action='store', type=str, metavar='OUTPUT') - # Not implemented: parser.add_argument('--generate-bom', action='store_true', default=True) - parser.add_argument('--prepend-file', action='store', type=str, metavar='YAML_FILE') - return parser.parse_args() +def _get_yaml_data_and_path(inp: Union[str, Path, Dict]) -> (Dict, Path): + # determine whether inp is a file path, a YAML string, or a Dict + if not isinstance(inp, Dict): # received a str or a Path + try: + yaml_path = Path(inp).expanduser().resolve(strict=True) + # if no FileNotFoundError exception happens, get file contents + yaml_str = open_file_read(yaml_path).read() + except (FileNotFoundError, OSError) as e: + # if inp is a long YAML string, Pathlib will raise OSError: [Errno 63] + # when trying to expand and resolve it as a path. + # Catch this error, but raise any others + if type(e) is OSError and e.errno != 63: + raise e + # file does not exist; assume inp is a YAML string + yaml_str = inp + yaml_path = None + yaml_data = yaml.safe_load(yaml_str) + else: + # received a Dict, use as-is + yaml_data = inp + yaml_path = None + return yaml_data, yaml_path + + +def _get_output_dir(input_file: Path, default_output_dir: Path) -> Path: + if default_output_dir: # user-specified output directory + output_dir = Path(default_output_dir) + else: # auto-determine appropriate output directory + if input_file: # input comes from a file; place output in same directory + output_dir = input_file.parent + else: # input comes from str or Dict; fall back to cwd + output_dir = Path.cwd() + return output_dir.resolve() + + +def _get_output_name(input_file: Path, default_output_name: Path) -> str: + if default_output_name: # user-specified output name + output_name = default_output_name + else: # auto-determine appropriate output name + if input_file: # input comes from a file; use same file stem + output_name = input_file.stem + else: # input comes from str or Dict; no fallback available + raise Exception("No output file name provided") + return output_name def main(): - - args = parse_cmdline() - - if not os.path.exists(args.input_file): - print(f'Error: input file {args.input_file} inaccessible or does not exist, check path') - sys.exit(1) - - with open_file_read(args.input_file) as fh: - yaml_input = fh.read() - - if args.prepend_file: - if not os.path.exists(args.prepend_file): - print(f'Error: prepend input file {args.prepend_file} inaccessible or does not exist, check path') - sys.exit(1) - with open_file_read(args.prepend_file) as fh: - prepend = fh.read() - yaml_input = prepend + yaml_input - - if not args.output_file: - file_out = args.input_file - pre, _ = os.path.splitext(file_out) - file_out = pre # extension will be added by graphviz output function - else: - file_out = args.output_file - file_out = os.path.abspath(file_out) - - parse(yaml_input, file_out=file_out) + print("When running from the command line, please use wv_cli.py instead.") -if __name__ == '__main__': +if __name__ == "__main__": main() diff --git a/src/wireviz/wv_bom.py b/src/wireviz/wv_bom.py index 56df752d..6689d79a 100644 --- a/src/wireviz/wv_bom.py +++ b/src/wireviz/wv_bom.py @@ -9,76 +9,108 @@ from wireviz.wv_gv_html import html_bgcolor_attr, html_line_breaks from wireviz.wv_helper import clean_whitespace -BOM_COLUMNS_ALWAYS = ('id', 'description', 'qty', 'unit', 'designators') -BOM_COLUMNS_OPTIONAL = ('pn', 'manufacturer', 'mpn', 'supplier', 'spn') -BOM_COLUMNS_IN_KEY = ('description', 'unit') + BOM_COLUMNS_OPTIONAL +BOM_COLUMNS_ALWAYS = ("id", "description", "qty", "unit", "designators") +BOM_COLUMNS_OPTIONAL = ("pn", "manufacturer", "mpn", "supplier", "spn") +BOM_COLUMNS_IN_KEY = ("description", "unit") + BOM_COLUMNS_OPTIONAL -HEADER_PN = 'P/N' -HEADER_MPN = 'MPN' -HEADER_SPN = 'SPN' +HEADER_PN = "P/N" +HEADER_MPN = "MPN" +HEADER_SPN = "SPN" BOMKey = Tuple[str, ...] BOMColumn = str # = Literal[*BOM_COLUMNS_ALWAYS, *BOM_COLUMNS_OPTIONAL] BOMEntry = Dict[BOMColumn, Union[str, int, float, List[str], None]] + def optional_fields(part: Union[Connector, Cable, AdditionalComponent]) -> BOMEntry: """Return part field values for the optional BOM columns as a dict.""" part = asdict(part) return {field: part.get(field) for field in BOM_COLUMNS_OPTIONAL} -def get_additional_component_table(harness: "Harness", component: Union[Connector, Cable]) -> List[str]: + +def get_additional_component_table( + harness: "Harness", component: Union[Connector, Cable] +) -> List[str]: """Return a list of diagram node table row strings with additional components.""" rows = [] if component.additional_components: rows.append(["Additional components"]) for part in component.additional_components: common_args = { - 'qty': part.qty * component.get_qty_multiplier(part.qty_multiplier), - 'unit': part.unit, - 'bgcolor': part.bgcolor, + "qty": part.qty * component.get_qty_multiplier(part.qty_multiplier), + "unit": part.unit, + "bgcolor": part.bgcolor, } if harness.options.mini_bom_mode: - id = get_bom_index(harness.bom(), bom_entry_key({**asdict(part), 'description': part.description})) - rows.append(component_table_entry(f'#{id} ({part.type.rstrip()})', **common_args)) + id = get_bom_index( + harness.bom(), + bom_entry_key({**asdict(part), "description": part.description}), + ) + rows.append( + component_table_entry( + f"#{id} ({part.type.rstrip()})", **common_args + ) + ) else: - rows.append(component_table_entry(part.description, **common_args, **optional_fields(part))) + rows.append( + component_table_entry( + part.description, **common_args, **optional_fields(part) + ) + ) return rows + def get_additional_component_bom(component: Union[Connector, Cable]) -> List[BOMEntry]: """Return a list of BOM entries with additional components.""" bom_entries = [] for part in component.additional_components: - bom_entries.append({ - 'description': part.description, - 'qty': part.qty * component.get_qty_multiplier(part.qty_multiplier), - 'unit': part.unit, - 'designators': component.name if component.show_name else None, - **optional_fields(part), - }) + bom_entries.append( + { + "description": part.description, + "qty": part.qty * component.get_qty_multiplier(part.qty_multiplier), + "unit": part.unit, + "designators": component.name if component.show_name else None, + **optional_fields(part), + } + ) return bom_entries + def bom_entry_key(entry: BOMEntry) -> BOMKey: """Return a tuple of string values from the dict that must be equal to join BOM entries.""" - if 'key' not in entry: - entry['key'] = tuple(clean_whitespace(make_str(entry.get(c))) for c in BOM_COLUMNS_IN_KEY) - return entry['key'] + if "key" not in entry: + entry["key"] = tuple( + clean_whitespace(make_str(entry.get(c))) for c in BOM_COLUMNS_IN_KEY + ) + return entry["key"] + def generate_bom(harness: "Harness") -> List[BOMEntry]: """Return a list of BOM entries generated from the harness.""" from wireviz.Harness import Harness # Local import to avoid circular imports + bom_entries = [] # connectors for connector in harness.connectors.values(): if not connector.ignore_in_bom: - description = ('Connector' - + (f', {connector.type}' if connector.type else '') - + (f', {connector.subtype}' if connector.subtype else '') - + (f', {connector.pincount} pins' if connector.show_pincount else '') - + (f', {translate_color(connector.color, harness.options.color_mode)}' if connector.color else '')) - bom_entries.append({ - 'description': description, 'designators': connector.name if connector.show_name else None, - **optional_fields(connector), - }) + description = ( + "Connector" + + (f", {connector.type}" if connector.type else "") + + (f", {connector.subtype}" if connector.subtype else "") + + (f", {connector.pincount} pins" if connector.show_pincount else "") + + ( + f", {translate_color(connector.color, harness.options.color_mode)}" + if connector.color + else "" + ) + ) + bom_entries.append( + { + "description": description, + "designators": connector.name if connector.show_name else None, + **optional_fields(connector), + } + ) # add connectors aditional components to bom bom_entries.extend(get_additional_component_bom(connector)) @@ -87,29 +119,58 @@ def generate_bom(harness: "Harness") -> List[BOMEntry]: # TODO: If category can have other non-empty values than 'bundle', maybe it should be part of description? for cable in harness.cables.values(): if not cable.ignore_in_bom: - if cable.category != 'bundle': + if cable.category != "bundle": # process cable as a single entity - description = ('Cable' - + (f', {cable.type}' if cable.type else '') - + (f', {cable.wirecount}') - + (f' x {cable.gauge} {cable.gauge_unit}' if cable.gauge else ' wires') - + ( ' shielded' if cable.shield else '') - + (f', {translate_color(cable.color, harness.options.color_mode)}' if cable.color else '')) - bom_entries.append({ - 'description': description, 'qty': cable.length, 'unit': cable.length_unit, 'designators': cable.name if cable.show_name else None, - **optional_fields(cable), - }) + description = ( + "Cable" + + (f", {cable.type}" if cable.type else "") + + (f", {cable.wirecount}") + + ( + f" x {cable.gauge} {cable.gauge_unit}" + if cable.gauge + else " wires" + ) + + (" shielded" if cable.shield else "") + + ( + f", {translate_color(cable.color, harness.options.color_mode)}" + if cable.color + else "" + ) + ) + bom_entries.append( + { + "description": description, + "qty": cable.length, + "unit": cable.length_unit, + "designators": cable.name if cable.show_name else None, + **optional_fields(cable), + } + ) else: # add each wire from the bundle to the bom for index, color in enumerate(cable.colors): - description = ('Wire' - + (f', {cable.type}' if cable.type else '') - + (f', {cable.gauge} {cable.gauge_unit}' if cable.gauge else '') - + (f', {translate_color(color, harness.options.color_mode)}' if color else '')) - bom_entries.append({ - 'description': description, 'qty': cable.length, 'unit': cable.length_unit, 'designators': cable.name if cable.show_name else None, - **{k: index_if_list(v, index) for k, v in optional_fields(cable).items()}, - }) + description = ( + "Wire" + + (f", {cable.type}" if cable.type else "") + + (f", {cable.gauge} {cable.gauge_unit}" if cable.gauge else "") + + ( + f", {translate_color(color, harness.options.color_mode)}" + if color + else "" + ) + ) + bom_entries.append( + { + "description": description, + "qty": cable.length, + "unit": cable.length_unit, + "designators": cable.name if cable.show_name else None, + **{ + k: index_if_list(v, index) + for k, v in optional_fields(cable).items() + }, + } + ) # add cable/bundles aditional components to bom bom_entries.extend(get_additional_component_bom(cable)) @@ -118,86 +179,111 @@ def generate_bom(harness: "Harness") -> List[BOMEntry]: bom_entries.extend(harness.additional_bom_items) # remove line breaks if present and cleanup any resulting whitespace issues - bom_entries = [{k: clean_whitespace(v) for k, v in entry.items()} for entry in bom_entries] + bom_entries = [ + {k: clean_whitespace(v) for k, v in entry.items()} for entry in bom_entries + ] # deduplicate bom bom = [] for _, group in groupby(sorted(bom_entries, key=bom_entry_key), key=bom_entry_key): group_entries = list(group) - designators = sum((make_list(entry.get('designators')) for entry in group_entries), []) - total_qty = sum(entry.get('qty', 1) for entry in group_entries) - bom.append({**group_entries[0], 'qty': round(total_qty, 3), 'designators': sorted(set(designators))}) + designators = sum( + (make_list(entry.get("designators")) for entry in group_entries), [] + ) + total_qty = sum(entry.get("qty", 1) for entry in group_entries) + bom.append( + { + **group_entries[0], + "qty": round(total_qty, 3), + "designators": sorted(set(designators)), + } + ) # add an incrementing id to each bom entry - return [{**entry, 'id': index} for index, entry in enumerate(bom, 1)] + return [{**entry, "id": index} for index, entry in enumerate(bom, 1)] + def get_bom_index(bom: List[BOMEntry], target: BOMKey) -> int: """Return id of BOM entry or raise exception if not found.""" for entry in bom: if bom_entry_key(entry) == target: - return entry['id'] - raise Exception('Internal error: No BOM entry found matching: ' + '|'.join(target)) + return entry["id"] + raise Exception("Internal error: No BOM entry found matching: " + "|".join(target)) + def bom_list(bom: List[BOMEntry]) -> List[List[str]]: """Return list of BOM rows as lists of column strings with headings in top row.""" keys = list(BOM_COLUMNS_ALWAYS) # Always include this fixed set of BOM columns. - for fieldname in BOM_COLUMNS_OPTIONAL: # Include only those optional BOM columns that are in use. + for fieldname in BOM_COLUMNS_OPTIONAL: + # Include only those optional BOM columns that are in use. if any(entry.get(fieldname) for entry in bom): keys.append(fieldname) # Custom mapping from internal name to BOM column headers. # Headers not specified here are generated by capitilising the internal name. bom_headings = { - 'pn': HEADER_PN, - 'mpn': HEADER_MPN, - 'spn': HEADER_SPN, + "pn": HEADER_PN, + "mpn": HEADER_MPN, + "spn": HEADER_SPN, } - return ([[bom_headings.get(k, k.capitalize()) for k in keys]] + # Create header row with key names - [[make_str(entry.get(k)) for k in keys] for entry in bom]) # Create string list for each entry row + return [ + [bom_headings.get(k, k.capitalize()) for k in keys] + ] + [ # Create header row with key names + [make_str(entry.get(k)) for k in keys] for entry in bom + ] # Create string list for each entry row + def component_table_entry( - type: str, - qty: Union[int, float], - unit: Optional[str] = None, - bgcolor: Optional[Color] = None, - pn: Optional[str] = None, - manufacturer: Optional[str] = None, - mpn: Optional[str] = None, - supplier: Optional[str] = None, - spn: Optional[str] = None, - ) -> str: + type: str, + qty: Union[int, float], + unit: Optional[str] = None, + bgcolor: Optional[Color] = None, + pn: Optional[str] = None, + manufacturer: Optional[str] = None, + mpn: Optional[str] = None, + supplier: Optional[str] = None, + spn: Optional[str] = None, +) -> str: """Return a diagram node table row string with an additional component.""" part_number_list = [ pn_info_string(HEADER_PN, None, pn), pn_info_string(HEADER_MPN, manufacturer, mpn), pn_info_string(HEADER_SPN, supplier, spn), ] - output = (f'{qty}' - + (f' {unit}' if unit else '') - + f' x {type}' - + ('
' if any(part_number_list) else '') - + (', '.join([pn for pn in part_number_list if pn]))) + output = ( + f"{qty}" + + (f" {unit}" if unit else "") + + f" x {type}" + + ("
" if any(part_number_list) else "") + + (", ".join([pn for pn in part_number_list if pn])) + ) # format the above output as left aligned text in a single visible cell # indent is set to two to match the indent in the generated html table - return f''' + return f"""
-
{html_line_breaks(output)}
''' + """ -def pn_info_string(header: str, name: Optional[str], number: Optional[str]) -> Optional[str]: + +def pn_info_string( + header: str, name: Optional[str], number: Optional[str] +) -> Optional[str]: """Return the company name and/or the part number in one single string or None otherwise.""" - number = str(number).strip() if number is not None else '' + number = str(number).strip() if number is not None else "" if name or number: return f'{name if name else header}{": " + number if number else ""}' else: return None + def index_if_list(value: Any, index: int) -> Any: """Return the value indexed if it is a list, or simply the value otherwise.""" return value[index] if isinstance(value, list) else value + def make_list(value: Any) -> list: """Return value if a list, empty list if None, or single element list otherwise.""" return value if isinstance(value, list) else [] if value is None else [value] + def make_str(value: Any) -> str: """Return comma separated elements if a list, empty string if None, or value as a string otherwise.""" - return ', '.join(str(element) for element in make_list(value)) + return ", ".join(str(element) for element in make_list(value)) diff --git a/src/wireviz/wv_cli.py b/src/wireviz/wv_cli.py new file mode 100644 index 00000000..73150720 --- /dev/null +++ b/src/wireviz/wv_cli.py @@ -0,0 +1,149 @@ +# -*- coding: utf-8 -*- + +import os +import sys +from pathlib import Path + +import click + +if __name__ == "__main__": + sys.path.insert(0, os.path.join(os.path.dirname(__file__), "..")) + +import wireviz.wireviz as wv +from wireviz import APP_NAME, __version__ +from wireviz.wv_helper import open_file_read + +format_codes = { + "c": "csv", + "g": "gv", + "h": "html", + "p": "png", + "P": "pdf", + "s": "svg", + "t": "tsv", +} + +epilog = "The -f or --format option accepts a string containing one or more of the " +epilog += "following characters to specify which file types to output:\n" +epilog += ", ".join([f"{key} ({value.upper()})" for key, value in format_codes.items()]) + + +@click.command(epilog=epilog, no_args_is_help=True) +@click.argument("file", nargs=-1) +@click.option( + "-f", + "--format", + default="hpst", + type=str, + show_default=True, + help="Output formats (see below).", +) +@click.option( + "-p", + "--prepend", + default=[], + multiple=True, + type=Path, + help="YAML file to prepend to the input file (optional).", +) +@click.option( + "-o", + "--output-dir", + default=None, + type=Path, + help="Directory to use for output files, if different from input file directory.", +) +@click.option( + "-O", + "--output-name", + default=None, + type=str, + help="File name (without extension) to use for output files, if different from input file name.", +) +@click.option( + "-V", + "--version", + is_flag=True, + default=False, + help=f"Output {APP_NAME} version and exit.", +) +def wireviz(file, format, prepend, output_dir, output_name, version): + """ + Parses the provided FILE and generates the specified outputs. + """ + print() + print(f"{APP_NAME} {__version__}") + if version: + return # print version number only and exit + + # get list of files + try: + _ = iter(file) + except TypeError: + filepaths = [file] + else: + filepaths = list(file) + + # determine output formats + output_formats = [] + for code in format: + if code in format_codes: + output_formats.append(format_codes[code]) + else: + raise Exception(f"Unknown output format: {code}") + output_formats = tuple(sorted(set(output_formats))) + output_formats_str = ( + f'[{"|".join(output_formats)}]' + if len(output_formats) > 1 + else output_formats[0] + ) + + # check prepend file + if len(prepend) > 0: + prepend_input = "" + for prepend_file in prepend: + prepend_file = Path(prepend_file) + if not prepend_file.exists(): + raise Exception(f"File does not exist:\n{prepend_file}") + print("Prepend file:", prepend_file) + + prepend_input += open_file_read(prepend_file).read() + "\n" + else: + prepend_input = "" + + # run WireVIz on each input file + for file in filepaths: + file = Path(file) + if not file.exists(): + raise Exception(f"File does not exist:\n{file}") + + # file_out = file.with_suffix("") if not output_file else output_file + _output_dir = file.parent if not output_dir else output_dir + _output_name = file.stem if not output_name else output_name + + print("Input file: ", file) + print( + "Output file: ", f"{Path(_output_dir / _output_name)}.{output_formats_str}" + ) + + yaml_input = open_file_read(file).read() + file_dir = file.parent + + yaml_input = prepend_input + yaml_input + image_paths = {file_dir} + for p in prepend: + image_paths.add(Path(p).parent) + + wv.parse( + yaml_input, + output_formats=output_formats, + output_dir=_output_dir, + output_name=_output_name, + image_paths=list(image_paths), + ) + + print() + + +if __name__ == "__main__": + wireviz() diff --git a/src/wireviz/wv_colors.py b/src/wireviz/wv_colors.py index e07ed53e..857f3077 100644 --- a/src/wireviz/wv_colors.py +++ b/src/wireviz/wv_colors.py @@ -3,181 +3,198 @@ from typing import Dict, List COLOR_CODES = { - 'DIN': ['WH', 'BN', 'GN', 'YE', 'GY', 'PK', 'BU', 'RD', 'BK', 'VT', 'GYPK', 'RDBU', 'WHGN', 'BNGN', 'WHYE', 'YEBN', - 'WHGY', 'GYBN', 'WHPK', 'PKBN', 'WHBU', 'BNBU', 'WHRD', 'BNRD', 'WHBK', 'BNBK', 'GYGN', 'YEGY', 'PKGN', - 'YEPK', 'GNBU', 'YEBU', 'GNRD', 'YERD', 'GNBK', 'YEBK', 'GYBU', 'PKBU', 'GYRD', 'PKRD', 'GYBK', 'PKBK', - 'BUBK', 'RDBK', 'WHBNBK', 'YEGNBK', 'GYPKBK', 'RDBUBK', 'WHGNBK', 'BNGNBK', 'WHYEBK', 'YEBNBK', 'WHGYBK', - 'GYBNBK', 'WHPKBK', 'PKBNBK', 'WHBUBK', 'BNBUBK', 'WHRDBK', 'BNRDBK'], - 'IEC': ['BN', 'RD', 'OG', 'YE', 'GN', 'BU', 'VT', 'GY', 'WH', 'BK'], - 'BW': ['BK', 'WH'], + # fmt: off + "DIN": [ + "WH", "BN", "GN", "YE", "GY", "PK", "BU", "RD", "BK", "VT", "GYPK", "RDBU", + "WHGN", "BNGN", "WHYE", "YEBN", "WHGY", "GYBN", "WHPK", "PKBN", "WHBU", "BNBU", + "WHRD", "BNRD", "WHBK", "BNBK", "GYGN", "YEGY", "PKGN", "YEPK", "GNBU", "YEBU", + "GNRD", "YERD", "GNBK", "YEBK", "GYBU", "PKBU", "GYRD", "PKRD", "GYBK", "PKBK", + "BUBK", "RDBK", "WHBNBK", "YEGNBK", "GYPKBK", "RDBUBK", "WHGNBK", "BNGNBK", + "WHYEBK", "YEBNBK", "WHGYBK", "GYBNBK", "WHPKBK", "PKBNBK", "WHBUBK", + "BNBUBK", "WHRDBK", "BNRDBK", + ], + # fmt: on + "IEC": ["BN", "RD", "OG", "YE", "GN", "BU", "VT", "GY", "WH", "BK"], + "BW": ["BK", "WH"], # 25-pair color code - see also https://en.wikipedia.org/wiki/25-pair_color_code # 5 major colors (WH,RD,BK,YE,VT) combined with 5 minor colors (BU,OG,GN,BN,SL). # Each POTS pair tip (+) had major/minor color, and ring (-) had minor/major color. - 'TEL': [ # 25x2: Ring and then tip of each pair - 'BUWH', 'WHBU', 'OGWH', 'WHOG', 'GNWH', 'WHGN', 'BNWH', 'WHBN', 'SLWH', 'WHSL', - 'BURD', 'RDBU', 'OGRD', 'RDOG', 'GNRD', 'RDGN', 'BNRD', 'RDBN', 'SLRD', 'RDSL', - 'BUBK', 'BKBU', 'OGBK', 'BKOG', 'GNBK', 'BKGN', 'BNBK', 'BKBN', 'SLBK', 'BKSL', - 'BUYE', 'YEBU', 'OGYE', 'YEOG', 'GNYE', 'YEGN', 'BNYE', 'YEBN', 'SLYE', 'YESL', - 'BUVT', 'VTBU', 'OGVT', 'VTOG', 'GNVT', 'VTGN', 'BNVT', 'VTBN', 'SLVT', 'VTSL'], - 'TELALT': [ # 25x2: Tip and then ring of each pair - 'WHBU', 'BU', 'WHOG', 'OG', 'WHGN', 'GN', 'WHBN', 'BN', 'WHSL', 'SL', - 'RDBU', 'BURD', 'RDOG', 'OGRD', 'RDGN', 'GNRD', 'RDBN', 'BNRD', 'RDSL', 'SLRD', - 'BKBU', 'BUBK', 'BKOG', 'OGBK', 'BKGN', 'GNBK', 'BKBN', 'BNBK', 'BKSL', 'SLBK', - 'YEBU', 'BUYE', 'YEOG', 'OGYE', 'YEGN', 'GNYE', 'YEBN', 'BNYE', 'YESL', 'SLYE', - 'VTBU', 'BUVT', 'VTOG', 'OGVT', 'VTGN', 'GNVT', 'VTBN', 'BNVT', 'VTSL', 'SLVT'], - 'T568A': ['WHGN', 'GN', 'WHOG', 'BU', 'WHBU', 'OG', 'WHBN', 'BN'], - 'T568B': ['WHOG', 'OG', 'WHGN', 'BU', 'WHBU', 'GN', 'WHBN', 'BN'], + # fmt: off + "TEL": [ # 25x2: Ring and then tip of each pair + "BUWH", "WHBU", "OGWH", "WHOG", "GNWH", "WHGN", "BNWH", "WHBN", "SLWH", "WHSL", + "BURD", "RDBU", "OGRD", "RDOG", "GNRD", "RDGN", "BNRD", "RDBN", "SLRD", "RDSL", + "BUBK", "BKBU", "OGBK", "BKOG", "GNBK", "BKGN", "BNBK", "BKBN", "SLBK", "BKSL", + "BUYE", "YEBU", "OGYE", "YEOG", "GNYE", "YEGN", "BNYE", "YEBN", "SLYE", "YESL", + "BUVT", "VTBU", "OGVT", "VTOG", "GNVT", "VTGN", "BNVT", "VTBN", "SLVT", "VTSL", + ], + "TELALT": [ # 25x2: Tip and then ring of each pair + "WHBU", "BU", "WHOG", "OG", "WHGN", "GN", "WHBN", "BN", "WHSL", "SL", + "RDBU", "BURD", "RDOG", "OGRD", "RDGN", "GNRD", "RDBN", "BNRD", "RDSL", "SLRD", + "BKBU", "BUBK", "BKOG", "OGBK", "BKGN", "GNBK", "BKBN", "BNBK", "BKSL", "SLBK", + "YEBU", "BUYE", "YEOG", "OGYE", "YEGN", "GNYE", "YEBN", "BNYE", "YESL", "SLYE", + "VTBU", "BUVT", "VTOG", "OGVT", "VTGN", "GNVT", "VTBN", "BNVT", "VTSL", "SLVT", + ], + # fmt: on + "T568A": ["WHGN", "GN", "WHOG", "BU", "WHBU", "OG", "WHBN", "BN"], + "T568B": ["WHOG", "OG", "WHGN", "BU", "WHBU", "GN", "WHBN", "BN"], } # Convention: Color names should be 2 letters long, to allow for multicolored wires _color_hex = { - 'BK': '#000000', - 'WH': '#ffffff', - 'GY': '#999999', - 'PK': '#ff66cc', - 'RD': '#ff0000', - 'OG': '#ff8000', - 'YE': '#ffff00', - 'OL': '#708000', # olive green - 'GN': '#00ff00', - 'TQ': '#00ffff', - 'LB': '#a0dfff', # light blue - 'BU': '#0066ff', - 'VT': '#8000ff', - 'BN': '#895956', - 'BG': '#ceb673', # beige - 'IV': '#f5f0d0', # ivory - 'SL': '#708090', - 'CU': '#d6775e', # Faux-copper look, for bare CU wire - 'SN': '#aaaaaa', # Silvery look for tinned bare wire - 'SR': '#84878c', # Darker silver for silvered wire - 'GD': '#ffcf80', # Golden color for gold + "BK": "#000000", + "WH": "#ffffff", + "GY": "#999999", + "PK": "#ff66cc", + "RD": "#ff0000", + "OG": "#ff8000", + "YE": "#ffff00", + "OL": "#708000", # olive green + "GN": "#00ff00", + "TQ": "#00ffff", + "LB": "#a0dfff", # light blue + "BU": "#0066ff", + "VT": "#8000ff", + "BN": "#895956", + "BG": "#ceb673", # beige + "IV": "#f5f0d0", # ivory + "SL": "#708090", + "CU": "#d6775e", # Faux-copper look, for bare CU wire + "SN": "#aaaaaa", # Silvery look for tinned bare wire + "SR": "#84878c", # Darker silver for silvered wire + "GD": "#ffcf80", # Golden color for gold } _color_full = { - 'BK': 'black', - 'WH': 'white', - 'GY': 'grey', - 'PK': 'pink', - 'RD': 'red', - 'OG': 'orange', - 'YE': 'yellow', - 'OL': 'olive green', - 'GN': 'green', - 'TQ': 'turquoise', - 'LB': 'light blue', - 'BU': 'blue', - 'VT': 'violet', - 'BN': 'brown', - 'BG': 'beige', - 'IV': 'ivory', - 'SL': 'slate', - 'CU': 'copper', - 'SN': 'tin', - 'SR': 'silver', - 'GD': 'gold', + "BK": "black", + "WH": "white", + "GY": "grey", + "PK": "pink", + "RD": "red", + "OG": "orange", + "YE": "yellow", + "OL": "olive green", + "GN": "green", + "TQ": "turquoise", + "LB": "light blue", + "BU": "blue", + "VT": "violet", + "BN": "brown", + "BG": "beige", + "IV": "ivory", + "SL": "slate", + "CU": "copper", + "SN": "tin", + "SR": "silver", + "GD": "gold", } _color_ger = { - 'BK': 'sw', - 'WH': 'ws', - 'GY': 'gr', - 'PK': 'rs', - 'RD': 'rt', - 'OG': 'or', - 'YE': 'ge', - 'OL': 'ol', # olivgrün - 'GN': 'gn', - 'TQ': 'tk', - 'LB': 'hb', # hellblau - 'BU': 'bl', - 'VT': 'vi', - 'BN': 'br', - 'BG': 'bg', # beige - 'IV': 'eb', # elfenbeinfarben - 'SL': 'si', # Schiefer - 'CU': 'ku', # Kupfer - 'SN': 'vz', # verzinkt - 'SR': 'ag', # Silber - 'GD': 'au', # Gold + "BK": "sw", + "WH": "ws", + "GY": "gr", + "PK": "rs", + "RD": "rt", + "OG": "or", + "YE": "ge", + "OL": "ol", # olivgrün + "GN": "gn", + "TQ": "tk", + "LB": "hb", # hellblau + "BU": "bl", + "VT": "vi", + "BN": "br", + "BG": "bg", # beige + "IV": "eb", # elfenbeinfarben + "SL": "si", # Schiefer + "CU": "ku", # Kupfer + "SN": "vz", # verzinkt + "SR": "ag", # Silber + "GD": "au", # Gold } -color_default = '#ffffff' +color_default = "#ffffff" -_hex_digits = set('0123456789abcdefABCDEF') +_hex_digits = set("0123456789abcdefABCDEF") # Literal type aliases below are commented to avoid requiring python 3.8 Color = str # Two-letter color name = Literal[_color_hex.keys()] Colors = str # One or more two-letter color names (Color) concatenated into one string -ColorMode = str # = Literal['full', 'FULL', 'hex', 'HEX', 'short', 'SHORT', 'ger', 'GER'] +ColorMode = ( + str # = Literal['full', 'FULL', 'hex', 'HEX', 'short', 'SHORT', 'ger', 'GER'] +) ColorScheme = str # Color scheme name = Literal[COLOR_CODES.keys()] def get_color_hex(input: Colors, pad: bool = False) -> List[str]: """Return list of hex colors from either a string of color names or :-separated hex colors.""" - if input is None or input == '': + if input is None or input == "": return [color_default] - elif input[0] == '#': # Hex color(s) - output = input.split(':') + elif input[0] == "#": # Hex color(s) + output = input.split(":") for i, c in enumerate(output): - if c[0] != '#' or not all(d in _hex_digits for d in c[1:]): + if c[0] != "#" or not all(d in _hex_digits for d in c[1:]): if c != input: - c += f' in input: {input}' - print(f'Invalid hex color: {c}') + c += f" in input: {input}" + print(f"Invalid hex color: {c}") output[i] = color_default else: # Color name(s) + def lookup(c: str) -> str: try: return _color_hex[c] except KeyError: if c != input: - c += f' in input: {input}' - print(f'Unknown color name: {c}') + c += f" in input: {input}" + print(f"Unknown color name: {c}") return color_default - output = [lookup(input[i:i + 2]) for i in range(0, len(input), 2)] + output = [lookup(input[i : i + 2]) for i in range(0, len(input), 2)] if len(output) == 2: # Give wires with EXACTLY 2 colors that striped look. output += output[:1] elif pad and len(output) == 1: # Hacky style fix: Give single color wires - output *= 3 # a triple-up so that wires are the same size. + output *= 3 # a triple-up so that wires are the same size. return output def get_color_translation(translate: Dict[Color, str], input: Colors) -> List[str]: """Return list of colors translations from either a string of color names or :-separated hex colors.""" + def from_hex(hex_input: str) -> str: for color, hex in _color_hex.items(): if hex == hex_input: return translate[color] return f'({",".join(str(int(hex_input[i:i+2], 16)) for i in range(1, 6, 2))})' - return [from_hex(h) for h in input.lower().split(':')] if input[0] == '#' else \ - [translate.get(input[i:i+2], '??') for i in range(0, len(input), 2)] + return ( + [from_hex(h) for h in input.lower().split(":")] + if input[0] == "#" + else [translate.get(input[i : i + 2], "??") for i in range(0, len(input), 2)] + ) def translate_color(input: Colors, color_mode: ColorMode) -> str: - if input == '' or input is None: - return '' + if input == "" or input is None: + return "" upper = color_mode.isupper() if not (color_mode.isupper() or color_mode.islower()): - raise Exception('Unknown color mode capitalization') + raise Exception("Unknown color mode capitalization") color_mode = color_mode.lower() - if color_mode == 'full': + if color_mode == "full": output = "/".join(get_color_translation(_color_full, input)) - elif color_mode == 'hex': - output = ':'.join(get_color_hex(input, pad=False)) - elif color_mode == 'ger': + elif color_mode == "hex": + output = ":".join(get_color_hex(input, pad=False)) + elif color_mode == "ger": output = "".join(get_color_translation(_color_ger, input)) - elif color_mode == 'short': + elif color_mode == "short": output = input else: - raise Exception('Unknown color mode') + raise Exception("Unknown color mode") if upper: return output.upper() else: diff --git a/src/wireviz/wv_gv_html.py b/src/wireviz/wv_gv_html.py index 0b843db5..ec80aa74 100644 --- a/src/wireviz/wv_gv_html.py +++ b/src/wireviz/wv_gv_html.py @@ -1,51 +1,72 @@ # -*- coding: utf-8 -*- -from typing import List, Optional, Union import re +from typing import List, Optional, Union from wireviz.DataClasses import Color from wireviz.wv_colors import translate_color from wireviz.wv_helper import remove_links -def nested_html_table(rows: List[Union[str, List[Optional[str]], None]], table_attrs: str = '') -> str: + +def nested_html_table( + rows: List[Union[str, List[Optional[str]], None]], table_attrs: str = "" +) -> str: # input: list, each item may be scalar or list # output: a parent table with one child table per parent item that is list, and one cell per parent item that is scalar # purpose: create the appearance of one table, where cell widths are independent between rows # attributes in any leading inside a list are injected into to the preceeding tag html = [] - html.append(f'') + html.append( + f'
' + ) + + num_rows = 0 for row in rows: if isinstance(row, List): if len(row) > 0 and any(row): - html.append(' ') + # fmt: off + html.append(f' '.replace(">
') + html.append("
") + # fmt: off html.append(' ') + # fmt: on for cell in row: if cell is not None: # Inject attributes to the preceeding '.replace('>
tag where needed - html.append(f' {cell}
') - html.append('
{cell}
") + html.append(" ") + num_rows = num_rows + 1 elif row is not None: - html.append(' ') - html.append(f' {row}') - html.append(' ') - html.append('') + html.append(" ") + html.append(f" {row}") + html.append(" ") + num_rows = num_rows + 1 + if num_rows == 0: # empty table + # generate empty cell to avoid GraphViz errors + html.append("") + html.append("") return html + def html_bgcolor_attr(color: Color) -> str: """Return attributes for bgcolor or '' if no color.""" - return f' bgcolor="{translate_color(color, "HEX")}"' if color else '' + return f' bgcolor="{translate_color(color, "HEX")}"' if color else "" + -def html_bgcolor(color: Color, _extra_attr: str = '') -> str: +def html_bgcolor(color: Color, _extra_attr: str = "") -> str: """Return attributes prefix for bgcolor or '' if no color.""" - return f'' if color else '' + return f"" if color else "" + def html_colorbar(color: Color) -> str: """Return attributes prefix for bgcolor and minimum width or None if no color.""" return html_bgcolor(color, ' width="4"') if color else None + def html_image(image): from wireviz.DataClasses import Image + if not image: return None # The leading attributes belong to the preceeding tag. See where used below. @@ -53,24 +74,38 @@ def html_image(image): if image.fixedsize: # Close the preceeding tag and enclose the image cell in a table without # borders to avoid narrow borders when the fixed width < the node width. - html = f'''> + html = f""">
- ''' - return f'''{html_line_breaks(image.caption)}' - if image and image.caption else None) + + return ( + f'{html_line_breaks(image.caption)}' + if image and image.caption + else None + ) + def html_size_attr(image): from wireviz.DataClasses import Image + # Return Graphviz HTML attributes to specify minimum or fixed size of a TABLE or TD object - return ((f' width="{image.width}"' if image.width else '') - + (f' height="{image.height}"' if image.height else '') - + ( ' fixedsize="true"' if image.fixedsize else '')) if image else '' + return ( + ( + (f' width="{image.width}"' if image.width else "") + + (f' height="{image.height}"' if image.height else "") + + (' fixedsize="true"' if image.fixedsize else "") + ) + if image + else "" + ) + def html_line_breaks(inp): - return remove_links(inp).replace('\n', '
') if isinstance(inp, str) else inp + return remove_links(inp).replace("\n", "
") if isinstance(inp, str) else inp diff --git a/src/wireviz/wv_helper.py b/src/wireviz/wv_helper.py index 6b78f173..a10f6acf 100644 --- a/src/wireviz/wv_helper.py +++ b/src/wireviz/wv_helper.py @@ -1,34 +1,37 @@ # -*- coding: utf-8 -*- -from typing import List import re +from pathlib import Path +from typing import Dict, List awg_equiv_table = { - '0.09': '28', - '0.14': '26', - '0.25': '24', - '0.34': '22', - '0.5': '21', - '0.75': '20', - '1': '18', - '1.5': '16', - '2.5': '14', - '4': '12', - '6': '10', - '10': '8', - '16': '6', - '25': '4', - '35': '2', - '50': '1', + "0.09": "28", + "0.14": "26", + "0.25": "24", + "0.34": "22", + "0.5": "21", + "0.75": "20", + "1": "18", + "1.5": "16", + "2.5": "14", + "4": "12", + "6": "10", + "10": "8", + "16": "6", + "25": "4", + "35": "2", + "50": "1", } -mm2_equiv_table = {v:k for k,v in awg_equiv_table.items()} +mm2_equiv_table = {v: k for k, v in awg_equiv_table.items()} + def awg_equiv(mm2): - return awg_equiv_table.get(str(mm2), 'Unknown') + return awg_equiv_table.get(str(mm2), "Unknown") + def mm2_equiv(awg): - return mm2_equiv_table.get(str(awg), 'Unknown') + return mm2_equiv_table.get(str(awg), "Unknown") def expand(yaml_data): @@ -41,8 +44,8 @@ def expand(yaml_data): yaml_data = [yaml_data] for e in yaml_data: e = str(e) - if '-' in e: - a, b = e.split('-', 1) + if "-" in e: + a, b = e.split("-", 1) try: a = int(a) b = int(b) @@ -55,7 +58,8 @@ def expand(yaml_data): else: # a == b output.append(a) # range of length 1 except: - output.append(e) # '-' was not a delimiter between two ints, pass e through unchanged + # '-' was not a delimiter between two ints, pass e through unchanged + output.append(e) else: try: x = int(e) # single int @@ -65,6 +69,12 @@ def expand(yaml_data): return output +def get_single_key_and_value(d: dict): + k = list(d.keys())[0] + v = d[k] + return (k, v) + + def int2tuple(inp): if isinstance(inp, tuple): output = inp @@ -74,45 +84,95 @@ def int2tuple(inp): def flatten2d(inp): - return [[str(item) if not isinstance(item, List) else ', '.join(item) for item in row] for row in inp] + return [ + [str(item) if not isinstance(item, List) else ", ".join(item) for item in row] + for row in inp + ] def tuplelist2tsv(inp, header=None): - output = '' + output = "" if header is not None: inp.insert(0, header) inp = flatten2d(inp) for row in inp: - output = output + '\t'.join(str(remove_links(item)) for item in row) + '\n' + output = output + "\t".join(str(remove_links(item)) for item in row) + "\n" return output def remove_links(inp): - return re.sub(r'<[aA] [^>]*>([^<]*)', r'\1', inp) if isinstance(inp, str) else inp + return ( + re.sub(r"<[aA] [^>]*>([^<]*)", r"\1", inp) + if isinstance(inp, str) + else inp + ) def clean_whitespace(inp): - return ' '.join(inp.split()).replace(' ,', ',') if isinstance(inp, str) else inp + return " ".join(inp.split()).replace(" ,", ",") if isinstance(inp, str) else inp def open_file_read(filename): # TODO: Intelligently determine encoding - return open(filename, 'r', encoding='UTF-8') + return open(filename, "r", encoding="UTF-8") + def open_file_write(filename): - return open(filename, 'w', encoding='UTF-8') + return open(filename, "w", encoding="UTF-8") + def open_file_append(filename): - return open(filename, 'a', encoding='UTF-8') + return open(filename, "a", encoding="UTF-8") + + +def is_arrow(inp): + """ + Matches strings of one or multiple `-` or `=` (but not mixed) + optionally starting with `<` and/or ending with `>`. + + Examples: + <-, --, ->, <-> + <==, ==, ==>, <=> + """ + # regex by @shiraneyo + return bool( + re.match(r"^\s*(?P-+|=+)(?P>?)\s*$", inp) + ) + def aspect_ratio(image_src): try: from PIL import Image + image = Image.open(image_src) if image.width > 0 and image.height > 0: return image.width / image.height - print(f'aspect_ratio(): Invalid image size {image.width} x {image.height}') + print(f"aspect_ratio(): Invalid image size {image.width} x {image.height}") # ModuleNotFoundError and FileNotFoundError are the most expected, but all are handled equally. except Exception as error: - print(f'aspect_ratio(): {type(error).__name__}: {error}') - return 1 # Assume 1:1 when unable to read actual image size + print(f"aspect_ratio(): {type(error).__name__}: {error}") + return 1 # Assume 1:1 when unable to read actual image size + + +def smart_file_resolve(filename: str, possible_paths: (str, List[str])) -> Path: + if not isinstance(possible_paths, List): + possible_paths = [possible_paths] + filename = Path(filename) + if filename.is_absolute(): + if filename.exists(): + return filename + else: + raise Exception(f"{filename} does not exist.") + else: # search all possible paths in decreasing order of precedence + possible_paths = [ + Path(path).resolve() for path in possible_paths if path is not None + ] + for possible_path in possible_paths: + resolved_path = (possible_path / filename).resolve() + if resolved_path.exists(): + return resolved_path + else: + raise Exception( + f"{filename} was not found in any of the following locations: \n" + + "\n".join([str(x) for x in possible_paths]) + ) diff --git a/src/wireviz/wv_html.py b/src/wireviz/wv_html.py index 0b819746..b30bdeeb 100644 --- a/src/wireviz/wv_html.py +++ b/src/wireviz/wv_html.py @@ -1,54 +1,119 @@ # -*- coding: utf-8 -*- -from pathlib import Path -from typing import List, Union import re +from pathlib import Path +from typing import Dict, List, Union -from wireviz import __version__, APP_NAME, APP_URL, wv_colors +from wireviz import APP_NAME, APP_URL, __version__, wv_colors from wireviz.DataClasses import Metadata, Options -from wireviz.wv_helper import flatten2d, open_file_read, open_file_write - -def generate_html_output(filename: Union[str, Path], bom_list: List[List[str]], metadata: Metadata, options: Options): - with open_file_write(f'{filename}.html') as file: - file.write('\n') - file.write('\n') - file.write(' \n') - file.write(f' \n') - file.write(f' {metadata["title"]}\n') - file.write(f'\n') - - file.write(f'

{metadata["title"]}

\n') - description = metadata.get('description') - if description: - file.write(f'

{description}

\n') - file.write('

Diagram

\n') - with open_file_read(f'{filename}.svg') as svg: - file.write(re.sub( - '^<[?]xml [^?>]*[?]>[^<]*]*>', - '', - svg.read(1024), 1)) - for svgdata in svg: - file.write(svgdata) - - file.write('

Bill of Materials

\n') - listy = flatten2d(bom_list) - file.write('\n') - file.write(' \n') - for item in listy[0]: - file.write(f' \n') - file.write(' \n') - for row in listy[1:]: - file.write(' \n') - for i, item in enumerate(row): - item_str = item.replace('\u00b2', '²') - align = '; text-align:right' if listy[0][i] == 'Qty' else '' - file.write(f' \n') - file.write(' \n') - file.write('
{item}
{item_str}
\n') - - notes = metadata.get('notes') - if notes: - file.write(f'

Notes

\n

{notes}

\n') - - file.write('\n') +from wireviz.wv_gv_html import html_line_breaks +from wireviz.wv_helper import ( + flatten2d, + open_file_read, + open_file_write, + smart_file_resolve, +) + + +def generate_html_output( + filename: Union[str, Path], + bom_list: List[List[str]], + metadata: Metadata, + options: Options, +): + + # load HTML template + templatename = metadata.get("template", {}).get("name") + if templatename: + # if relative path to template was provided, check directory of YAML file first, fall back to built-in template directory + templatefile = smart_file_resolve( + f"{templatename}.html", + [Path(filename).parent, Path(__file__).parent / "templates"], + ) + else: + # fall back to built-in simple template if no template was provided + templatefile = Path(__file__).parent / "templates/simple.html" + + html = open_file_read(templatefile).read() + + # embed SVG diagram + with open_file_read(f"{filename}.svg") as file: + svgdata = re.sub( + "^<[?]xml [^?>]*[?]>[^<]*]*>", + "", + file.read(), + 1, + ) + + # generate BOM table + bom = flatten2d(bom_list) + + # generate BOM header (may be at the top or bottom of the table) + bom_header_html = " \n" + for item in bom[0]: + th_class = f"bom_col_{item.lower()}" + bom_header_html = f'{bom_header_html} {item}\n' + bom_header_html = f"{bom_header_html} \n" + + # generate BOM contents + bom_contents = [] + for row in bom[1:]: + row_html = " \n" + for i, item in enumerate(row): + td_class = f"bom_col_{bom[0][i].lower()}" + row_html = f'{row_html} {item}\n' + row_html = f"{row_html} \n" + bom_contents.append(row_html) + + bom_html = ( + '\n' + bom_header_html + "".join(bom_contents) + "
\n" + ) + bom_html_reversed = ( + '\n' + + "".join(list(reversed(bom_contents))) + + bom_header_html + + "
\n" + ) + + # prepare simple replacements + replacements = { + "": f"{APP_NAME} {__version__} - {APP_URL}", + "": options.fontname, + "": wv_colors.translate_color(options.bgcolor, "hex"), + "": svgdata, + "": bom_html, + "": bom_html_reversed, + "": "1", # TODO: handle multi-page documents + "": "1", # TODO: handle multi-page documents + } + + # prepare metadata replacements + if metadata: + for item, contents in metadata.items(): + if isinstance(contents, (str, int, float)): + replacements[f""] = html_line_breaks(str(contents)) + elif isinstance(contents, Dict): # useful for authors, revisions + for index, (category, entry) in enumerate(contents.items()): + if isinstance(entry, Dict): + replacements[f""] = str(category) + for entry_key, entry_value in entry.items(): + replacements[ + f"" + ] = html_line_breaks(str(entry_value)) + + replacements['"sheetsize_default"'] = '"{}"'.format( + metadata.get("template", {}).get("sheetsize", "") + ) + # include quotes so no replacement happens within