implement first component renderer classes - Resistors

Author: dragoncoder047

schemascii/annoline.py

@@ -85,7 +85,7 @@ def find_all(cls, grid: _grid.Grid) -> list[AnnotationLine]:
                     seen_points.update(line.points)
         return all_lines
 
-    def render(self, data, **options) -> str:
+    def render(self, **options) -> str:
         # copy-pasted from wire.py except class changed at bottom
         # create lines for all of the neighbor pairs
         links = []

schemascii/annotation.py

@@ -15,7 +15,7 @@ class Annotation(_dc.DataConsumer, namespaces=(":annotation",)):
 
     options = [
         ("scale",),
-        _dc.Option("font", str, "Text font", "monospace"),
+        _dc.Option("font", str, "Text font", "sans-serif"),
     ]
 
     position: complex
@@ -34,7 +34,7 @@ def find_all(cls, grid: _grid.Grid):
                 out.append(cls(complex(x, y), text))
         return out
 
-    def render(self, data, scale, font) -> str:
+    def render(self, scale, font, **options) -> str:
         return _utils.XML.text(
             html.escape(self.content),
             x=self.position.real * scale,

schemascii/component.py

@@ -17,7 +17,15 @@
 class Component(_dc.DataConsumer, namespaces=(":component",)):
     """An icon representing a single electronic component."""
     all_components: typing.ClassVar[dict[str, type[Component]]] = {}
-    human_name: typing.ClassVar[str] = ""
+
+    options = [
+        "inherit",
+        _dc.Option("offset_scale", float,
+                   "How far to offset the label from the center of the "
+                   "component. Relative to the global scale option.", 1),
+        _dc.Option("font", str, "Text font for labels", "monospace"),
+
+    ]
 
     rd: _rd.RefDes
     blobs: list[list[complex]]  # to support multiple parts.
@@ -113,10 +121,13 @@ def from_rd(cls, rd: _rd.RefDes, grid: _grid.Grid) -> Component:
         # done
         return cls(rd, blobs, terminals)
 
-    def __init_subclass__(
-            cls, ids: list[str], id_letters: str | None = None, **kwargs):
+    def __init_subclass__(cls, ids: tuple[str, ...] = None,
+                          namespaces: tuple[str, ...] = None, **kwargs):
         """Register the component subclass in the component registry."""
-        super().__init_subclass__(**kwargs)
+        super().__init_subclass__(namespaces=(namespaces or ()), **kwargs)
+        if not ids:
+            # allow anonymous helper classes
+            return
         for id_letters in ids:
             if not (id_letters.isalpha() and id_letters.upper() == id_letters):
                 raise ValueError(
@@ -125,7 +136,6 @@ def __init_subclass__(
                 raise ValueError(
                     f"duplicate reference designator letters: {id_letters!r}")
             cls.all_components[id_letters] = cls
-        cls.human_name = id_letters or cls.__name__
 
     @property
     def css_class(self) -> str:
@@ -134,25 +144,34 @@ def css_class(self) -> str:
     @classmethod
     def process_nets(self, nets: list[_net.Net]):
         """Hook method called to do stuff with the nets that this
-        component type connects to. By itself it does nothing.
+        component type connects to. By default it does nothing.
 
         If a subclass implements this method to do something, it should
-        mutate the list in-place and return None.
+        mutate the list in-place (the return value is ignored).
         """
         pass
 
+    def get_terminals(
+            self, *flags_names: str) -> list[_utils.Terminal]:
+        """Return the component's terminals sorted so that the terminals with
+        the specified flags appear first in the order specified and the
+        remaining terminals come after.
 
-if __name__ == '__main__':
-    class FooComponent(Component, ids=["U", "FOO"]):
-        pass
-    print(Component.all_components)
-    testgrid = _grid.Grid("test_data/stresstest.txt")
-    # this will erroneously search the DATA section too but that's OK
-    # for this test
-    for rd in _rd.RefDes.find_all(testgrid):
-        c = Component.from_rd(rd, testgrid)
-        print(c)
-        for blob in c.blobs:
-            testgrid.spark(*blob)
-        testgrid.spark(*(t.pt for t in c.terminals))
-    Component(None, None, None)
+        Raises an error if a terminal with the specified flag could not be
+        found, or there were multiple terminals with the requested flag
+        (ambiguous).
+        """
+        out = []
+        for flag in flags_names:
+            matching_terminals = [t for t in self.terminals if t.flag == flag]
+            if len(matching_terminals) > 1:
+                raise _errors.TerminalsError(
+                    f"{self.rd.name}: multiple terminals with the "
+                    f"same flag {flag!r}")
+            if len(matching_terminals) == 0:
+                raise _errors.TerminalsError(
+                    f"{self.rd.name}: need a terminal with flag {flag!r}")
+            out.append(matching_terminals[0])
+        out.extend(t for t in self.terminals if t.flag not in flags_names)
+        assert set(self.terminals) == set(out)
+        return out

schemascii/components/__init__.py

@@ -0,0 +1,48 @@
+import typing
+from dataclasses import dataclass
+
+import schemascii.component as _c
+import schemascii.errors as _errors
+
+# TODO: import all of the component subclasses to register them
+
+
+@dataclass
+class NTerminalComponent(_c.Component):
+    """Represents a component that only ever has N terminals.
+
+    The class must have an attribute n_terminals with the number
+    of terminals."""
+    n_terminals: typing.ClassVar[int]
+
+    def __post_init__(self):
+        if self.n_terminals != len(self.terminals):
+            raise _errors.TerminalsError(
+                f"{self.rd.name}: can only have {self.n_terminals} terminals "
+                f"(found {len(self.terminals)})")
+
+
+class TwoTerminalComponent(NTerminalComponent):
+    """Shortcut to define a component with two terminals."""
+    n_terminals: typing.Final = 2
+
+
+@dataclass
+class PolarizedTwoTerminalComponent(TwoTerminalComponent):
+    """Helper class that ensures that a component has only two terminals,
+    and if provided, sorts the terminals so that the "+" terminal comes
+    first in the list.
+    """
+
+    always_polarized: typing.ClassVar[bool] = False
+
+    def __post_init__(self):
+        super().__post_init__()  # check count of terminals
+        num_plus = sum(t.flag == "+" for t in self.terminals)
+        if (self.always_polarized and num_plus != 1) or num_plus > 1:
+            raise _errors.TerminalsError(
+                f"{self.rd.name}: need '+' on only one terminal to indicate "
+                "polarization")
+        if self.terminals[1].flag == "+":
+            # swap first and last
+            self.terminals.insert(0, self.terminals.pop(-1))

schemascii/components/resistor.py

@@ -0,0 +1,64 @@
+from cmath import phase, pi, rect
+
+import schemascii.components as _c
+import schemascii.data_consumer as _dc
+import schemascii.utils as _utils
+import schemascii.errors as _errors
+
+# TODO: IEC rectangular symbol
+# see here: https://eepower.com/resistor-guide/resistor-standards-and-codes/resistor-symbols/  # noqa: E501
+
+
+def _ansi_resistor_squiggle(t1: complex, t2: complex) -> list[complex]:
+    vec = t1 - t2
+    length = abs(vec)
+    angle = phase(vec)
+    quad_angle = angle + pi / 2
+    points = [t1]
+    for i in range(1, 4 * int(length)):
+        points.append(t1 - rect(i / 4, angle)
+                      + (rect(1/4, quad_angle) * pow(-1, i)))
+    points.append(t2)
+    return points
+
+
+class Resistor(_c.TwoTerminalComponent, ids=("R",), namespaces=(":resistor",)):
+    options = [
+        "inherit",
+        _dc.Option("value", str, "Resistance in ohms"),
+        _dc.Option("power", str, "Maximum power dissipation in watts "
+                   "(i.e. size of the resistor)", None)
+    ]
+
+    is_variable = False
+
+    def render(self, value: str, power: str, **options) -> str:
+        t1, t2 = self.terminals[0].pt, self.terminals[1].pt
+        points = _ansi_resistor_squiggle(t1, t2)
+        try:
+            id_text = _utils.id_text(self.rd.name, self.terminals,
+                                     ((value, "Ω", False, self.is_variable),
+                                      (power, "W", False)),
+                                     _utils.make_text_point(t1, t2, **options),
+                                     **options)
+        except ValueError as e:
+            raise _errors.BOMError(
+                f"{self.rd.name}: Range of values not allowed "
+                "on fixed resistor") from e
+        return _utils.polylinegon(points, **options) + id_text
+
+
+class VariableResistor(Resistor, ids=("VR", "RV")):
+    is_variable = True
+
+    def render(self, **options):
+        t1, t2 = self.terminals[0].pt, self.terminals[1].pt
+        return (super().render(**options)
+                + _utils.make_variable(
+                    (t1 + t2) / 2, phase(t1 - t2), **options))
+
+# TODO: potentiometers
+
+
+if __name__ == "__main__":
+    print(Resistor.all_components)

schemascii/components_render.py

@@ -100,38 +100,6 @@ def sort_terminals(
     return sort_terminals
 
 
-@component("R", "RV", "VR")
-@n_terminal(2)
-@no_ambiguous
-def resistor(box: Cbox, terminals: list[Terminal],
-             bom_data: BOMData, **options):
-    """Resistor, Variable resistor, etc.
-    bom:ohms[,watts]"""
-    t1, t2 = terminals[0].pt, terminals[1].pt
-    vec = t1 - t2
-    mid = (t1 + t2) / 2
-    length = abs(vec)
-    angle = phase(vec)
-    quad_angle = angle + pi / 2
-    points = [t1]
-    for i in range(1, 4 * int(length)):
-        points.append(t1 - rect(i / 4, angle) + pow(-1, i)
-                      * rect(1, quad_angle) / 4)
-    points.append(t2)
-    return (
-        polylinegon(points, **options)
-        + make_variable(mid, angle, "V" in box.type, **options)
-        + id_text(
-            box,
-            bom_data,
-            terminals,
-            (("Ω", False), ("W", False)),
-            make_text_point(t1, t2, **options),
-            **options,
-        )
-    )
-
-
 @component("C", "CV", "VC")
 @n_terminal(2)
 @no_ambiguous

schemascii/data_consumer.py

@@ -2,6 +2,7 @@
 
 import abc
 import typing
+import warnings
 from dataclasses import dataclass
 
 import schemascii.data as _data
@@ -29,7 +30,7 @@ class DataConsumer(abc.ABC):
     to be rendered. This class registers the options that the class
     declares with Data so that they can be checked, automatically pulls
     the needed options when to_xml_string() is called, and passes the dict of
-    options to render().
+    options to render() as keyword arguments.
     """
 
     options: typing.ClassVar[list[Option
@@ -40,14 +41,25 @@ class DataConsumer(abc.ABC):
         Option("linewidth", float, "Width of drawn lines", 2),
         Option("color", str, "black", "Default color for everything"),
     ]
-    namepaces: tuple[str, ...]
     css_class: typing.ClassVar[str] = ""
 
-    def __init_subclass__(cls, namespaces: tuple[str, ...] = ("*",)):
+    @property
+    def namespaces(self) -> tuple[str, ...]:
+        # base case to stop recursion
+        return ()
+
+    def __init_subclass__(cls, namespaces: tuple[str, ...] = None):
+
+        if not namespaces:
+            # allow anonymous helper subclasses
+            return
 
         if not hasattr(cls, "namespaces"):
-            # don't clobber it if a subclass defines it as a @property!
-            cls.namespaces = namespaces
+            # don't clobber it if a subclass already overrides it!
+            @property
+            def __namespaces(self) -> tuple[str, ...]:
+                return super(type(self), self).namespaces + namespaces
+            cls.namepaces = __namespaces
 
         for b in cls.mro():
             if (b is not cls
@@ -97,14 +109,14 @@ def to_xml_string(self, data: _data.Data) -> str:
             if opt.name not in values:
                 if opt.default is _NOT_SET:
                     raise _errors.NoDataError(
-                        f"value for {self.namespaces[0]}.{name} is required")
+                        f"missing value for {self.namespaces[0]}.{name}")
                 values[opt.name] = opt.default
                 continue
             if isinstance(opt.type, list):
                 if values[opt.name] not in opt.type:
-                    raise _errors.DataTypeError(
-                        f"option {self.namespaces[0]}.{opt.name}: "
-                        f"invalid choice: {values[opt.name]} "
+                    raise _errors.BOMError(
+                        f"{self.namespaces[0]}.{opt.name}: "
+                        f"invalid choice: {values[opt.name]!r} "
                         f"(valid options are "
                         f"{', '.join(map(repr, opt.type))})")
                 continue
@@ -114,7 +126,13 @@ def to_xml_string(self, data: _data.Data) -> str:
                 raise _errors.DataTypeError(
                     f"option {self.namespaces[0]}.{opt.name}: "
                     f"invalid {opt.type.__name__} value: "
-                    f"{values[opt.name]}") from err
+                    f"{values[opt.name]!r}") from err
+        for key in values:
+            if any(opt.name == key for opt in self.options):
+                continue
+            warnings.warn(
+                f"unknown data key {key!r} for styling {self.namespaces[0]}",
+                stacklevel=2)
         # render
         result = self.render(**values, data=data)
         if self.css_class:

schemascii/drawing.py

@@ -83,7 +83,7 @@ def to_xml_string(
             data |= fudge
         return super().to_xml_string(data)
 
-    def render(self, data, scale: float, padding: float) -> str:
+    def render(self, data, scale: float, padding: float, **options) -> str:
         # render everything
         content = _utils.XML.g(
             _utils.XML.g(

schemascii/errors.py

@@ -6,7 +6,7 @@ class DiagramSyntaxError(SyntaxError, Error):
     """Bad formatting in Schemascii diagram syntax."""
 
 
-class TerminalsError(TypeError, Error):
+class TerminalsError(ValueError, Error):
     """Incorrect usage of terminals on this component."""
 
 
@@ -22,5 +22,5 @@ class NoDataError(NameError, Error):
     """Data item is required, but not present."""
 
 
-class DataTypeError(ValueError, Error):
-    """Invalid data value."""
+class DataTypeError(TypeError, Error):
+    """Invalid data type in data section."""

schemascii/metric.py

@@ -94,7 +94,8 @@ def format_metric_unit(
         num: str,
         unit: str = "",
         six: bool = False,
-        unicode: bool = True) -> str:
+        unicode: bool = True,
+        allow_range: bool = True) -> str:
     """Normalizes the Metric multiplier on the number, then adds the unit.
 
     * If there is a suffix on num, moves it to after the unit.
@@ -106,6 +107,8 @@ def format_metric_unit(
     num = num.strip()
     match = METRIC_RANGE.match(num)
     if match:
+        if not allow_range:
+            raise ValueError("range not allowed")
         # format the range by calling recursively
         num0, num1 = match.group(1), match.group(2)
         suffix = num[match.span()[1]:]