add DataConsumer bases to simplify data-getting from Data instances

Author: dragoncoder047

schemascii/annoline.py

@@ -1,19 +1,26 @@
 from __future__ import annotations
+
+import itertools
+import typing
 from collections import defaultdict
 from dataclasses import dataclass
-from typing import ClassVar
-import schemascii.utils as _utils
+
+import schemascii.data_consumer as _dc
 import schemascii.grid as _grid
+import schemascii.utils as _utils
 
 
 @dataclass
-class AnnotationLine:
+class AnnotationLine(_dc.DataConsumer,
+                     namespaces=(":annotation", ":annotation-line")):
     """Class that implements the ability to
     draw annotation lines on the drawing
     without having to use a disconnected wire.
     """
 
-    directions: ClassVar[
+    css_class = "annotation annotation-line"
+
+    directions: typing.ClassVar[
         defaultdict[str, defaultdict[complex, list[complex]]]] = defaultdict(
         lambda: None, {
             # allow jumps over actual wires
@@ -36,7 +43,7 @@ class AnnotationLine:
                 1: [-1j, -1]
             }
         })
-    start_dirs: ClassVar[
+    start_dirs: typing.ClassVar[
         defaultdict[str, list[complex]]] = defaultdict(
         lambda: None, {
             "~": _utils.LEFT_RIGHT,
@@ -45,6 +52,7 @@ class AnnotationLine:
             "'": (-1, 1, 1j),
         })
 
+    # the sole member
     points: list[complex]
 
     @classmethod
@@ -77,6 +85,15 @@ def find_all(cls, grid: _grid.Grid) -> list[AnnotationLine]:
                     seen_points.update(line.points)
         return all_lines
 
+    def render(self, **options) -> str:
+        # copy-pasted from wire.py except class changed at bottom
+        # create lines for all of the neighbor pairs
+        links = []
+        for p1, p2 in itertools.combinations(self.points, 2):
+            if abs(p1 - p2) == 1:
+                links.append((p1, p2))
+        return _utils.bunch_o_lines(links, **options)
+
 
 if __name__ == '__main__':
     x = _grid.Grid("", """
@@ -90,6 +107,6 @@ def find_all(cls, grid: _grid.Grid) -> list[AnnotationLine]:
                            '~~~~~~~~~~~~~~~'
 
 """)
-    line = AnnotationLine.get_from_grid(x, 30+2j)
+    line, = AnnotationLine.find_all(x)
     print(line)
     x.spark(*line.points)

schemascii/annotation.py

@@ -1,18 +1,22 @@
 import re
 from dataclasses import dataclass
 
+import schemascii.data_consumer as _dc
 import schemascii.grid as _grid
+import schemascii.utils as _utils
 
 ANNOTATION_RE = re.compile(r"\[([^\]]+)\]")
 
 
 @dataclass
-class Annotation:
+class Annotation(_dc.DataConsumer, namespaces=(":annotation",)):
     """A chunk of text that will be rendered verbatim in the output SVG."""
 
     position: complex
     content: str
 
+    css_class = "annotation"
+
     @classmethod
     def find_all(cls, grid: _grid.Grid):
         """Return all of the text annotations present in the grid."""
@@ -23,3 +27,7 @@ def find_all(cls, grid: _grid.Grid):
                 text = match.group(1)
                 out.append(cls(complex(x, y), text))
         return out
+
+    def render(self, **options) -> str:
+        raise NotImplementedError
+        return _utils.XML.text()

schemascii/component.py

@@ -1,11 +1,10 @@
 from __future__ import annotations
 
-import abc
+import typing
 from collections import defaultdict
 from dataclasses import dataclass
-from typing import ClassVar
 
-import schemascii.data as _data
+import schemascii.data_consumer as _dc
 import schemascii.errors as _errors
 import schemascii.grid as _grid
 import schemascii.net as _net
@@ -15,15 +14,19 @@
 
 
 @dataclass
-class Component(abc.ABC):
+class Component(_dc.DataConsumer, namespaces=(":component",)):
     """An icon representing a single electronic component."""
-    all_components: ClassVar[dict[str, type[Component]]] = {}
-    human_name: ClassVar[str] = ""
+    all_components: typing.ClassVar[dict[str, type[Component]]] = {}
+    human_name: typing.ClassVar[str] = ""
 
     rd: _rd.RefDes
     blobs: list[list[complex]]  # to support multiple parts.
     terminals: list[_utils.Terminal]
 
+    @property
+    def namespaces(self) -> tuple[str, ...]:
+        return self.rd.name, self.rd.short_name, self.rd.letter, ":component"
+
     @classmethod
     def from_rd(cls, rd: _rd.RefDes, grid: _grid.Grid) -> Component:
         """Find the outline of the component and its terminals
@@ -122,27 +125,17 @@ def __init_subclass__(cls, ids: list[str], id_letters: str | None = None):
             cls.all_components[id_letters] = cls
         cls.human_name = id_letters or cls.__name__
 
-    def to_xml_string(self, options: _data.Data) -> str:
-        """Render this component to a string of SVG XML."""
-        return _utils.XML.g(
-            self.render(options.get_values_for(self.rd.name)),
-            class_=f"component {self.rd.letter}")
-
-    @abc.abstractmethod
-    def render(self, options: dict) -> str:
-        """Render this component to a string of XML using the options.
-        Component subclasses should implement this method.
-
-        This is a private method and should not be called directly. Instead,
-        use the `to_xml_string` method which performs a few more
-        transformations and wraps the output in a nicely formatted `<g>`.
-        """
-        raise NotImplementedError
+    @property
+    def css_class(self) -> str:
+        return f"component {self.rd.letter}"
 
     @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.
+
+        If a subclass implements this method to do something, it should
+        mutate the list in-place and return None.
         """
         pass
 

schemascii/data.py

@@ -2,12 +2,13 @@
 
 import fnmatch
 import re
+import typing
 from dataclasses import dataclass
-from typing import Any, TypeVar
 
+import schemascii.data_consumer as _dc
 import schemascii.errors as _errors
 
-T = TypeVar("T")
+T = typing.TypeVar("T")
 TOKEN_PAT = re.compile("|".join([
     r"[\n{};=]",  # special one-character
     "%%",  # comment marker
@@ -16,7 +17,6 @@
     r"""(?:(?!["\s{};=]).)+""",  # anything else
 ]))
 SPECIAL = {";", "\n", "%%", "{", "}"}
-_NOT_SET = object()
 
 
 def tokenize(stuff: str) -> list[str]:
@@ -40,10 +40,28 @@ def matches(self, name) -> bool:
 
 @dataclass
 class Data:
-    """Class that holds the data of a drawing."""
+    """Class that manages data defining drawing parameters.
+
+    The class object itself manages what data options are allowed for
+    what namespaces (e.g. to generate a help message) and can parse the data.
+
+    Instances of this class represent a collection of data sections that were
+    found in a drawing.
+    """
 
     sections: list[Section]
 
+    allowed_options: typing.ClassVar[dict[str, list[_dc.Option]]] = {}
+
+    @classmethod
+    def define_option(cls, ns: str, opt: _dc.Option):
+        if ns in cls.allowed_options:
+            if any(eo.name == opt.name for eo in cls.allowed_options[ns]):
+                raise ValueError(f"duplicate option name {opt.name!r}")
+            cls.allowed_options[ns].append(opt)
+        else:
+            cls.allowed_options[ns] = [opt]
+
     @classmethod
     def parse_from_string(cls, text: str, startline=1, filename="") -> Data:
         """Parses the data from the text.
@@ -54,7 +72,7 @@ def parse_from_string(cls, text: str, startline=1, filename="") -> Data:
         tokens = tokenize(text)
         lines = (text + "\n").splitlines()
         col = line = index = 0
-        lastsig = (0, 0, 0)
+        lastsig: tuple[int, int, int] = (0, 0, 0)
 
         def complain(msg):
             raise _errors.DiagramSyntaxError(
@@ -96,7 +114,7 @@ def eat():
         def save():
             return (index, line, col)
 
-        def restore(dat):
+        def restore(dat: tuple[int, int, int]):
             nonlocal index
             nonlocal line
             nonlocal col
@@ -210,17 +228,7 @@ def get_values_for(self, namespace: str) -> dict:
                 out |= section.data
         return out
 
-    def getopt(self, namespace: str, name: str, default: T = _NOT_SET) -> T:
-        values = self.get_values_for(namespace)
-        value = values.get(name, _NOT_SET)
-        if value is _NOT_SET:
-            if default is _NOT_SET:
-                raise _errors.NoDataError(
-                    f"value for {namespace}.{name} is required")
-            return default
-        return value
-
-    def __or__(self, other: Data | dict[str, Any] | Any) -> Data:
+    def __or__(self, other: Data | dict[str, typing.Any] | typing.Any) -> Data:
         if isinstance(other, dict):
             other = Data([Section("*", other)])
         if not isinstance(other, Data):

schemascii/data_consumer.py

@@ -0,0 +1,129 @@
+from __future__ import annotations
+
+import abc
+import typing
+from dataclasses import dataclass
+
+import schemascii.data as _data
+import schemascii.errors as _errors
+import schemascii.utils as _utils
+
+T = typing.TypeVar("T")
+_NOT_SET = object()
+
+
+@dataclass
+class Option(typing.Generic[T]):
+    """Represents an allowed name used in Schemascii's internals
+    somewhere. Normal users have no need for this class.
+    """
+
+    name: str
+    type: type[T] | list[T]
+    help: str
+    default: T = _NOT_SET
+
+
+class DataConsumer(abc.ABC):
+    """Base class for any Schemascii AST node that needs data
+    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: typing.ClassVar[list[Option
+                                  | typing.Literal["inherit"]
+                                  | tuple[str, ...]]] = [
+        Option("scale", float, "Scale by which to enlarge the "
+               "entire diagram by", 15),
+        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, ...] = ("*",)):
+
+        if not hasattr(cls, "namespaces"):
+            # don't clobber it if a subclass defines it as a @property!
+            cls.namespaces = namespaces
+
+        for b in cls.mro():
+            if (b is not cls
+                    and issubclass(b, DataConsumer)
+                    and b.options is cls.options):
+                # if we literally just inherit the attribute,
+                # don't bother reprocessing it
+                return
+
+        def coalesce_options(cls: type[DataConsumer]) -> list[Option]:
+            if DataConsumer not in cls.mro():
+                return []
+            seen_inherit = False
+            opts = []
+            for opt in cls.options:
+                if opt == "inherit":
+                    if seen_inherit:
+                        raise ValueError("can't use 'inherit' twice")
+
+                    seen_inherit = True
+                elif isinstance(opt, tuple):
+                    for base in cls.__bases__:
+                        opts.extend(o for o in coalesce_options(base)
+                                    if o.name in opt)
+                elif isinstance(opt, Option):
+                    opts.append(opt)
+                else:
+                    raise TypeError(f"unknown option definition: {opt!r}")
+            return opts
+
+        cls.options = coalesce_options(cls)
+        for ns in namespaces:
+            for option in cls.options:
+                _data.Data.define_option(ns, option)
+
+    def to_xml_string(self, data: _data.Data) -> str:
+        """Pull options relevant to this node from data, calls
+        self.render(), and wraps the output in a <g>."""
+        values = {}
+        for name in self.namespaces:
+            values |= data.get_values_for(name)
+        # validate the options
+        for opt in self.options:
+            if opt.name not in values:
+                if opt.default is _NOT_SET:
+                    raise _errors.NoDataError(
+                        f"value for {self.namespaces[0]}.{name} is required")
+                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]} "
+                        f"(valid options are "
+                        f"{', '.join(map(repr, opt.type))})")
+                continue
+            try:
+                values[opt.name] = opt.type(values[opt.name])
+            except ValueError as err:
+                raise _errors.DataTypeError(
+                    f"option {self.namespaces[0]}.{opt.name}: "
+                    f"invalid {opt.type.__name__} value: "
+                    f"{values[opt.name]}") from err
+        # render
+        result = self.render(**values, data=data)
+        if self.css_class:
+            result = _utils.XML.g(result, class_=self.css_class)
+        return result
+
+    @abc.abstractmethod
+    def render(self, data: _data.Data, **options) -> str:
+        """Render self to a string of XML. This is a private method and should
+        not be called by non-Schemascii-extending code. External callers should
+        call to_xml_string() instead.
+
+        Subclasses must implement this method.
+        """
+        raise NotImplementedError