update options handling and readme

Author: dragoncoder047

README.md

@@ -10,4 +10,51 @@ A command-line tool and library for converting ASCII-art diagrams into beautiful
 
 Works with Python 3.10+. It uses the new `match` feature in a few places. If you need to run Schemascii on an older version of Python, feel free to fork it and send me a pull request.
 
+Command line usage:
+
+```usage
+usage: schemascii [-h] [-V] [-o OUT_FILE] [--padding PADDING] [--scale SCALE] [--stroke_width STROKE_WIDTH] [--stroke STROKE]
+                  [--label {L,V,VL}]
+                  in_file
+
+Render ASCII-art schematics into SVG.
+
+positional arguments:
+  in_file               File to process.
+
+options:
+  -h, --help            show this help message and exit
+  -V, --version         show program's version number and exit
+  -o OUT_FILE, --out OUT_FILE
+                        Output SVG file. (default input file plus .svg)
+  --padding PADDING     Amount of padding to add on the edges.
+  --scale SCALE         Scale at which to enlarge the entire diagram by.
+  --stroke_width STROKE_WIDTH
+                        Width of the lines
+  --stroke STROKE       Color of the lines.
+  --label {L,V,VL}      Component label style (L=include label, V=include value, VL=both)
+```
+
+Python usage example:
+
+```python
+import schemascii
+
+# Render a file
+svg = schemascii.render("my_circuit.txt")
+
+# Render a string
+text = ... # this is the text of your file
+svg = schemascii.render("<string>", text)
+
+# Provide options
+svg = schemascii.render("my_circuit.txt",
+    padding=10,
+    scale=15,
+    stroke_width=2,
+    stroke="black",
+    label="LV")
+# these are the defaults
+```
+
 <!-- https://realpython.com/pypi-publish-python-package/ -->

schemascii/__init__.py

@@ -7,12 +7,22 @@
 
 __version__ = "0.1.0"
 
+default_options = {
+    'padding': 10,
+    'scale': 15,
+    'stroke_width': 2,
+    'stroke': 'black',
+    'label': 'LV',
+}
+
 
 def render(filename: str, text: str = None, **options) -> str:
     "Render the Schemascii diagram to an SVG string."
     if text is None:
         with open(filename, encoding="ascii") as f:
             text = f.read()
+    # default options
+    options = default_options | options
     # get everything
     grid = Grid(filename, text)
     components, bom_data = find_all(grid)
@@ -21,8 +31,8 @@ def render(filename: str, text: str = None, **options) -> str:
                           b.id == c.id and b.type == c.type]
                       for c in components}
     # get some options
-    padding = options.get('padding', 1)
-    scale = options.get('scale', 1)
+    padding = options['padding']
+    scale = options['scale']
 
     wires = get_wires(grid, **options)
     components_strs = (render_component(

schemascii/__main__.py

@@ -19,24 +19,19 @@ def cli_main():
                     help="Output SVG file. (default input file plus .svg)")
     ap.add_argument("--padding",
                     help="Amount of padding to add on the edges.",
-                    type=int,
-                    default=10)
+                    type=int)
     ap.add_argument("--scale",
                     help="Scale at which to enlarge the entire diagram by.",
-                    type=int,
-                    default=15)
+                    type=int)
     ap.add_argument("--stroke_width",
                     help="Width of the lines",
-                    type=int,
-                    default=2)
+                    type=int)
     ap.add_argument("--stroke",
-                    help="Color of the lines.",
-                    default="black")
+                    help="Color of the lines.")
     ap.add_argument("--label",
                     help="Component label style "
                     "(L=include label, V=include value, VL=both)",
-                    choices="L V VL".split(),
-                    default="VL")
+                    choices="L V VL".split())
     args = ap.parse_args()
     if args.out_file is None:
         args.out_file = args.in_file + ".svg"

schemascii/components_render.py

@@ -1,6 +1,7 @@
 from typing import Callable
 from cmath import phase, rect
 from math import pi
+from warnings import warn
 from .utils import (Cbox, Terminal, BOMData, XML, Side,
                     polylinegon, id_text, make_text_point,
                     bunch_o_lines, deep_transform, make_plus, make_variable)
@@ -200,17 +201,17 @@ def integrated_circuit(
         bom_data: BOMData | None,
         **options):
     "Draw an IC"
-    label_style = options.get("label", "VL")
-    scale = options.get("scale", 1)
+    label_style = options["label"]
+    scale = options["scale"]
     sz = (box.p2 - box.p1) * scale
     mid = (box.p2 + box.p1) * scale / 2
     out = XML.rect(
         x=box.p1.real * scale,
         y=box.p1.imag * scale,
         width=sz.real,
         height=sz.imag,
-        stroke__width=options.get("stroke_width", 1),
-        stroke=options.get("stroke", "black"),
+        stroke__width=options["stroke_width"],
+        stroke=options["stroke"],
         fill="none")
     for term in terminals:
         out += bunch_o_lines([(
@@ -225,9 +226,9 @@ def integrated_circuit(
         x=mid.real,
         y=mid.imag,
         text__anchor="middle",
-        font__size=options.get("scale", 1),
-        fill=options.get("stroke", "black"))
-    print("IC's in progress...")
+        font__size=options["scale"],
+        fill=options["stroke"])
+    warn("ICs are not fully implemented yet.")
     return out
 
 # code for drawing

schemascii/utils.py

@@ -112,9 +112,9 @@ def mk_tag(*contents, **attrs) -> str:
 
 def polylinegon(points: list[complex], is_polygon: bool = False, **options):
     "Turn the list of points into a <polyline> or <polygon>."
-    scale = options.get("scale", 1)
-    w = options.get("stroke_width", 0.15)
-    c = options.get("stroke", "black")
+    scale = options["scale"]
+    w = options["stroke_width"]
+    c = options["stroke"]
     pts = ' '.join(
         f'{x.real * scale},{x.imag * scale}'
         for x in points)
@@ -126,9 +126,9 @@ def polylinegon(points: list[complex], is_polygon: bool = False, **options):
 def bunch_o_lines(points: list[tuple[complex, complex]], **options):
     "Return a <line> for each pair of points."
     out = ''
-    scale = options.get('scale', 1)
-    w = options.get("stroke_width", 0.15)
-    c = options.get("stroke", "black")
+    scale = options['scale']
+    w = options["stroke_width"]
+    c = options["stroke"]
     for p1, p2 in points:
         out += XML.line(
             x1=p1.real * scale,
@@ -148,7 +148,7 @@ def id_text(
         point: complex | None = None,
         **options):
     "Format the component ID and value around the point"
-    label_style = options.get("label", "VL")
+    label_style = options["label"]
     if point is None:
         point = sum(t.pt for t in terminals) / len(terminals)
     data = ""
@@ -176,14 +176,14 @@ def id_text(
             any(Side.BOTTOM == t.side for t in terminals)
             or any(Side.TOP == t.side for t in terminals)
         ) else "middle",
-        font__size=options.get("scale", 1),
-        fill=options.get("stroke", "black"))
+        font__size=options["scale"],
+        fill=options["stroke"])
 
 
 def make_text_point(t1: complex, t2: complex, **options) -> complex:
     "Compute the scaled coordinates of the text anchor point."
     quad_angle = phase(t1 - t2) + pi / 2
-    scale = options.get("scale", 1)
+    scale = options["scale"]
     text_pt = (t1 + t2) * scale / 2
     offset = rect(scale / 2, quad_angle)
     text_pt += complex(abs(offset.real), -abs(offset.imag))

schemascii/wires.py

@@ -94,9 +94,9 @@ def blank_wire(grid: Grid, p1: complex, p2: complex):
 def next_wire(grid: Grid, **options) -> str | None:
     """Returns a SVG string of the next line in the grid,
     or None if there are no more. The line is masked off."""
-    scale = options.get("scale", 1)
-    stroke_width = options.get("stroke_width", 1)
-    color = options.get("stroke", "black")
+    scale = options["scale"]
+    stroke_width = options["stroke_width"]
+    color = options["stroke"]
     # Find the first wire or return None
     for i, line in enumerate(grid.lines):
         indexes = [line.index(c) for c in '-|()*' if c in line]