Release v0.4.1

docs/CONTRIBUTING.md

@@ -1,6 +1,6 @@
 # Contribution Guidelines
 
-When contributing to this repository, please [submit a new issue](https://github.com/formatc1702/WireViz/issues) first to discuss the proposed change, before submitting a pull request.
+When contributing to this repository, please [submit a new issue](https://github.com/wireviz/WireViz/issues) first to discuss the proposed change, before submitting a pull request.
 
 ## Submitting a new Issue
 
@@ -27,7 +27,7 @@ When contributing to this repository, please [submit a new issue](https://github
 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.
+  - If your code changes or extends the WireViz YAML syntax, be sure to update the [syntax description document](https://github.com/wireviz/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.
 
 ### Hints

docs/buildscript.md

@@ -2,7 +2,7 @@
 
 <!--
 The following text is taken from #118
-https://github.com/formatc1702/WireViz/pull/118
+https://github.com/wireviz/WireViz/pull/118
 
 TODO: write a better explaination -->
 

docs/syntax.md

@@ -319,6 +319,8 @@ connections:
 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.
 
+The default character to trigger autogeneration of components is `.`. A different character can be specified using the `template_separator` option (see below).
+
 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.
 
 
@@ -353,6 +355,7 @@ If any component is defined in the `connectors` or `cables` sections but not ref
   # If no value is specified for 'title', then the
   # output filename without extension is used.
 ```
+See [HTML Output Templates](../src/wireviz/templates/) for how metadata entries can be inserted into the HTML output.
 
 ## Options
 
@@ -387,6 +390,9 @@ If any component is defined in the `connectors` or `cables` sections but not ref
   # about additional components inside the diagram node (connector/cable box).
   # If False, show all info about additional components inside the diagram node.
   mini_bom_mode: <bool>        # Default = True
+
+  # Character to split template and designator for autogenerated components
+  template_separator: <str>    # Default = '.'
 ```
 
 

setup.py

@@ -27,6 +27,7 @@
     keywords="cable connector hardware harness wiring wiring-diagram wiring-harness",
     url=APP_URL,
     package_dir={"": "src"},
+    package_data={CMD_NAME: ["templates/*.html"]},
     packages=find_packages("src"),
     entry_points={
         "console_scripts": [

src/wireviz/Harness.py

@@ -20,7 +20,7 @@
     Tweak,
     Side,
 )
-from wireviz.svgembed import embed_svg_images_file
+from wireviz.svgembed import embed_svg_images, embed_svg_images_file
 from wireviz.wv_bom import (
     HEADER_MPN,
     HEADER_PN,
@@ -44,11 +44,10 @@
 )
 from wireviz.wv_helper import (
     awg_equiv,
+    file_write_text,
     flatten2d,
     is_arrow,
     mm2_equiv,
-    open_file_read,
-    open_file_write,
     tuplelist2tsv,
 )
 from wireviz.wv_html import generate_html_output
@@ -172,7 +171,7 @@ def create_graph(self) -> Graph:
             bgcolor=wv_colors.translate_color(self.options.bgcolor, "HEX"),
             nodesep="0.33",
             fontname=self.options.fontname,
-        )
+        )  # TODO: Add graph attribute: charset="utf-8",
         dot.attr(
             "node",
             shape="none",
@@ -253,6 +252,9 @@ def create_graph(self) -> Graph:
 
                 pinhtml.append("  </table>")
 
+                if len(pinhtml) == 2:  # Table start and end with no rows between?
+                    pinhtml = ["<!-- all pins hidden -->"]  # Avoid Graphviz error
+
                 html = [
                     row.replace("<!-- connector table -->", "\n".join(pinhtml))
                     for row in html
@@ -281,6 +283,7 @@ def create_graph(self) -> Graph:
                     dot.edge(
                         f"{connector.name}:p{loop[0]}{loop_side}:{loop_dir}",
                         f"{connector.name}:p{loop[1]}{loop_side}:{loop_dir}",
+                        label=" ",  # Work-around to avoid over-sized loops.
                     )
 
         # determine if there are double- or triple-colored wires in the harness;
@@ -530,6 +533,38 @@ def create_graph(self) -> Graph:
                 fillcolor=translate_color(bgcolor, "HEX"),
             )
 
+        # mates
+        for mate in self.mates:
+            if mate.shape[-1] == ">":
+                dir = "both" if mate.shape[0] == "<" else "forward"
+            else:
+                dir = "back" if mate.shape[0] == "<" else "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]
+            to_connector = self.connectors[mate.to_name]
+            if isinstance(mate, MatePin) and from_connector.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 to_connector.style != "simple":
+                to_pin_index = to_connector.pins.index(mate.to_pin)
+                to_port_str = f":p{to_pin_index+1}l"
+            else:  # MateComponent or style == 'simple'
+                to_port_str = ""
+            code_from = f"{mate.from_name}{from_port_str}:e"
+            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)
+
         def typecheck(name: str, value: Any, expect: type) -> None:
             if not isinstance(value, expect):
                 raise Exception(
@@ -595,51 +630,9 @@ def typecheck(name: str, value: Any, expect: type) -> None:
                 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)
+        # Tweak processing above must be the last before returning dot.
+        # Please don't insert any code that might change the dot contents
+        # after tweak processing.
 
         return dot
 
@@ -664,7 +657,7 @@ def png(self):
         return data.read()
 
     @property
-    def svg(self):
+    def svg(self):  # TODO?: Verify xml encoding="utf-8" in SVG?
         graph = self.graph
         return embed_svg_images(graph.pipe(format="svg").decode("utf-8"), Path.cwd())
 
@@ -699,7 +692,7 @@ def output(
         # BOM output
         bomlist = bom_list(self.bom())
         if "tsv" in fmt:
-            open_file_write(f"{filename}.bom.tsv").write(tuplelist2tsv(bomlist))
+            file_write_text(f"{filename}.bom.tsv", tuplelist2tsv(bomlist))
         if "csv" in fmt:
             # TODO: implement CSV output (preferrably using CSV library)
             print("CSV output is not yet supported")

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"
+__version__ = "0.4.1-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"
+APP_URL = "https://github.com/wireviz/WireViz"

src/wireviz/svgembed.py

@@ -8,6 +8,20 @@
 mime_subtype_replacements = {"jpg": "jpeg", "tif": "tiff"}
 
 
+# TODO: Share cache and code between data_URI_base64() and embed_svg_images()
+def data_URI_base64(file: Union[str, Path], media: str = "image") -> str:
+    """Return Base64-encoded data URI of input file."""
+    file = Path(file)
+    b64 = base64.b64encode(file.read_bytes()).decode("utf-8")
+    uri = f"data:{media}/{get_mime_subtype(file)};base64, {b64}"
+    # print(f"data_URI_base64('{file}', '{media}') -> {len(uri)}-character URI")
+    if len(uri) > 65535:
+        print(
+            "data_URI_base64(): Warning: Browsers might have different URI length limitations"
+        )
+    return uri
+
+
 def embed_svg_images(svg_in: str, base_path: Union[str, Path] = Path.cwd()) -> str:
     images_b64 = {}  # cache of base64-encoded images
 
@@ -45,8 +59,8 @@ def embed_svg_images_file(
 ) -> None:
     filename_in = Path(filename_in).resolve()
     filename_out = filename_in.with_suffix(".b64.svg")
-    filename_out.write_text(
+    filename_out.write_text(  # TODO?: Verify xml encoding="utf-8" in SVG?
         embed_svg_images(filename_in.read_text(), filename_in.parent)
-    )
+    )  # TODO: Use encoding="utf-8" in both read_text() and write_text()
     if overwrite:
         filename_out.replace(filename_in)

src/wireviz/templates/README.md

@@ -0,0 +1,52 @@
+# HTML Output Templates
+
+This is the standard folder where WireViz looks for an HTML output template file.
+
+## Which HTML Output Template File is Used?
+
+A named HTML output template can optionally be specified as
+`metadata.template.name` in the YAML input:
+```yaml
+metadata:
+  template:
+    name: din-6771
+```
+In the case above, WireViz will search for a template file named
+`din-6771.html` in these folders:
+1. In the same folder as the YAML input file.
+2. In this standard template folder.
+
+If no HTML output template is specified, the `simple` template is assumed
+(i.e. filename `simple.html`, and in this case,
+only the standard template folder is searched).
+
+## Placeholders in HTML Output Templates
+
+HTML output template files might contain placeholders that will be replaced by
+generated text by WireViz when producing HTML output based on such a template.
+A placeholder starts with `<!-- %`, followed by a keyword, and finally `% -->`.
+Note that there must be one single space between `--` and `%` at both ends.
+
+| Placeholder | Replaced by |
+| --- | --- |
+| `<!-- %generator% -->` | The application name, version, and URL |
+| `<!-- %fontname% -->`  | The value of `options.fontname` |
+| `<!-- %bgcolor% -->`   | The HEX color translation of `options.bgcolor` |
+| `<!-- %filename% -->`  | The output path and filename without extension |
+| `<!-- %filename_stem% -->` | The output filename without path nor extension |
+| `<!-- %bom% -->`           | BOM as HTML table with headers at top |
+| `<!-- %bom_reversed% -->`  | Reversed BOM as HTML table with headers at bottom |
+| `<!-- %sheet_current% -->` | `1` (multi-page documents not yet supported) |
+| `<!-- %sheet_total% -->`   | `1` (multi-page documents not yet supported) |
+| `<!-- %diagram% -->`       | Embedded SVG diagram as valid HTML |
+| `<!-- %diagram_png_b64% -->`  | Embedded base64 encoded PNG diagram as URI |
+| `<!-- %{item}% -->`           | String or numeric value of `metadata.{item}` |
+| `<!-- %{item}_{i}% -->`       | Category number `{i}` within dict value of `metadata.{item}` |
+| `<!-- %{item}_{i}_{key}% -->` | Value of `metadata.{item}.{category}.{key}` |
+| `<!-- %template_sheetsize% -->` | Value of `metadata.template.sheetsize` |
+
+Note that `{item}`, `{category}` and `{key}` in the description above can be
+any valid YAML key, and `{i}` is an integer representing the 1-based index of
+category entries in a dict `metadata.{item}` entry.
+The `{` and `}` characters are not literally part of the syntax, just used in
+this documentation to enclose the variable parts of the keywords.